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

ostruct/cli/file_utils.py

@@ -46,13 +46,14 @@ import codecs
 import glob
 import logging
 import os
-from typing import Any, Dict, List, Optional, Type, Union
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple, Type, Union
 
 import chardet
 
 from .errors import (
     DirectoryNotFoundError,
-    FileNotFoundError,
+    OstructFileNotFoundError,
     PathSecurityError,
 )
 from .file_info import FileInfo
@@ -113,10 +114,10 @@ def collect_files_from_pattern(
     pattern: str,
     security_manager: SecurityManager,
 ) -> List[FileInfo]:
-    """Collect files matching a glob pattern.
+    """Collect files matching a glob pattern or exact file path.
 
     Args:
-        pattern: Glob pattern to match files
+        pattern: Glob pattern or file path to match
         security_manager: Security manager for path validation
 
     Returns:
@@ -125,7 +126,18 @@ def collect_files_from_pattern(
     Raises:
         PathSecurityError: If any matched file is outside base directory
     """
-    # Expand pattern
+    # First check if it's an exact file path
+    if os.path.isfile(pattern):
+        try:
+            file_info = FileInfo.from_path(pattern, security_manager)
+            return [file_info]
+        except PathSecurityError:
+            raise
+        except Exception as e:
+            logger.warning("Could not process file %s: %s", pattern, str(e))
+            return []
+
+    # If not an exact file, try glob pattern
     matched_paths = glob.glob(pattern, recursive=True)
     if not matched_paths:
         logger.debug("No files matched pattern: %s", pattern)
@@ -140,8 +152,8 @@ def collect_files_from_pattern(
         except PathSecurityError:
             # Let security errors propagate
             raise
-        except Exception:
-            logger.warning("Could not process file %s", path)
+        except Exception as e:
+            logger.warning("Could not process file %s: %s", path, str(e))
 
     return files
 
@@ -256,20 +268,21 @@ def collect_files_from_directory(
                     raise
 
                 try:
+                    # Use absolute path when creating FileInfo
                     file_info = FileInfo.from_path(
-                        rel_path, security_manager=security_manager, **kwargs
+                        abs_path, security_manager=security_manager, **kwargs
                     )
                     files.append(file_info)
-                    logger.debug("Added file to list: %s", rel_path)
+                    logger.debug("Added file to list: %s", abs_path)
                 except PathSecurityError as e:
                     # Log and re-raise security errors immediately
                     logger.error(
                         "Security violation processing file: %s (%s)",
-                        rel_path,
+                        abs_path,
                         str(e),
                     )
                     raise
-                except (FileNotFoundError, PermissionError) as e:
+                except (OstructFileNotFoundError, PermissionError) as e:
                     # Skip legitimate file access errors
                     logger.warning(
                         "Skipping inaccessible file: %s (error: %s)",
@@ -289,39 +302,34 @@ def collect_files_from_directory(
 
 
 def _validate_and_split_mapping(
-    mapping: str, mapping_type: str
+    mapping: tuple[str, Union[str, Path]], mapping_type: str
 ) -> tuple[str, str]:
-    """Validate and split a name=value mapping.
+    """Validate a name/path tuple mapping.
 
     Args:
-        mapping: The mapping string to validate (e.g. "name=value")
+        mapping: The mapping tuple (name, path)
         mapping_type: Type of mapping for error messages ("file", "pattern", or "directory")
 
     Returns:
-        Tuple of (name, value)
+        The same tuple of (name, path)
 
     Raises:
         ValueError: If mapping format is invalid
     """
-    try:
-        name, value = mapping.split("=", 1)
-    except ValueError:
-        raise ValueError(
-            f"Invalid {mapping_type} mapping format: {mapping!r} (missing '=' separator)"
-        )
+    name, value = mapping
 
     if not name:
-        raise ValueError(f"Empty name in {mapping_type} mapping: {mapping!r}")
+        raise ValueError(f"Empty name in {mapping_type} mapping")
     if not value:
-        raise ValueError(f"Empty value in {mapping_type} mapping: {mapping!r}")
+        raise ValueError(f"Empty value in {mapping_type} mapping")
 
-    return name, value
+    return name, str(value)  # Convert Path to str if needed
 
 
 def collect_files(
-    file_mappings: Optional[List[str]] = None,
-    pattern_mappings: Optional[List[str]] = None,
-    dir_mappings: Optional[List[str]] = None,
+    file_mappings: Optional[List[Tuple[str, Union[str, Path]]]] = None,
+    pattern_mappings: Optional[List[Tuple[str, Union[str, Path]]]] = None,
+    dir_mappings: Optional[List[Tuple[str, Union[str, Path]]]] = None,
     dir_recursive: bool = False,
     dir_extensions: Optional[List[str]] = None,
     security_manager: Optional[SecurityManager] = None,
@@ -330,9 +338,9 @@ def collect_files(
     """Collect files from multiple sources.
 
     Args:
-        file_mappings: List of file mappings in the format "name=path"
-        pattern_mappings: List of pattern mappings in the format "name=pattern"
-        dir_mappings: List of directory mappings in the format "name=directory"
+        file_mappings: List of file mappings as (name, path) tuples
+        pattern_mappings: List of pattern mappings as (name, pattern) tuples
+        dir_mappings: List of directory mappings as (name, directory) tuples
         dir_recursive: Whether to process directories recursively
         dir_extensions: List of file extensions to include in directory processing
         security_manager: Security manager instance
@@ -383,7 +391,7 @@ def collect_files(
                 raise ValueError(f"Duplicate file mapping: {name}")
 
             file_info = FileInfo.from_path(
-                path, security_manager=security_manager, **kwargs
+                str(path), security_manager=security_manager, **kwargs
             )
             files[name] = FileInfoList([file_info], from_dir=False)
             logger.debug("Added single file mapping: %s -> %s", name, path)
@@ -398,7 +406,7 @@ def collect_files(
 
             try:
                 matched_files = collect_files_from_pattern(
-                    pattern, security_manager=security_manager, **kwargs
+                    str(pattern), security_manager=security_manager, **kwargs
                 )
             except PathSecurityError as e:
                 logger.debug("Security error in pattern mapping: %s", str(e))
@@ -465,7 +473,7 @@ def collect_files(
 
     if not files:
         logger.debug("No files found in any mappings")
-        raise ValueError("No files found")
+        return files
 
     logger.debug("Collected files total mappings: %d", len(files))
     return files
@@ -609,14 +617,14 @@ def read_allowed_dirs_from_file(filepath: str) -> List[str]:
         A list of allowed directories as absolute paths.
 
     Raises:
-        FileNotFoundError: If the file does not exist.
+        OstructFileNotFoundError: If the file does not exist.
         ValueError: If the file contains invalid data.
     """
     try:
         with open(filepath, "r") as f:
             lines = f.readlines()
     except OSError as e:
-        raise FileNotFoundError(
+        raise OstructFileNotFoundError(
             f"Error reading allowed directories from file: {filepath}: {e}"
         )
 

ostruct/cli/path_utils.py

@@ -1,17 +1,21 @@
 """Path validation utilities for the CLI."""
 
+import logging
 from pathlib import Path
 from typing import Optional, Tuple
 
 from ostruct.cli.errors import (
     DirectoryNotFoundError,
-    FileNotFoundError,
+    OstructFileNotFoundError,
+    PathSecurityError,
     VariableNameError,
     VariableValueError,
 )
-from ostruct.cli.security.errors import PathSecurityError, SecurityErrorReasons
+from ostruct.cli.security.errors import SecurityErrorReasons
 from ostruct.cli.security.security_manager import SecurityManager
 
+logger = logging.getLogger(__name__)
+
 
 def validate_path_mapping(
     mapping: str,
@@ -44,34 +48,52 @@ def validate_path_mapping(
         >>> validate_path_mapping("data=config/", is_dir=True)  # Validates directory
         ('data', 'config/')
     """
+    logger.debug(
+        "Validating path mapping: %s (is_dir=%s, base_dir=%s)",
+        mapping,
+        is_dir,
+        base_dir,
+    )
+
     # Split into name and path parts
     try:
         name, path_str = mapping.split("=", 1)
     except ValueError:
+        logger.error("Invalid mapping format (missing '='): %s", mapping)
         raise ValueError(f"Invalid mapping format (missing '='): {mapping}")
 
     # Validate name
     name = name.strip()
     if not name:
+        logger.error("Variable name cannot be empty: %s", mapping)
         raise VariableNameError("Variable name cannot be empty")
     if not name.isidentifier():
+        logger.error("Invalid variable name: %s", name)
         raise VariableNameError(f"Invalid variable name: {name}")
 
     # Normalize path
     path_str = path_str.strip()
     if not path_str:
+        logger.error("Path cannot be empty: %s", mapping)
         raise VariableValueError("Path cannot be empty")
 
+    logger.debug("Creating Path object for: %s", path_str)
     # Create a Path object
     path = Path(path_str)
     if not path.is_absolute() and base_dir:
+        logger.debug(
+            "Converting relative path to absolute using base_dir: %s", base_dir
+        )
         path = Path(base_dir) / path
 
     # Validate path with security manager if provided
     if security_manager:
+        logger.debug("Validating path with security manager: %s", path)
         try:
             path = security_manager.validate_path(path)
+            logger.debug("Security validation passed: %s", path)
         except PathSecurityError as e:
+            logger.error("Security validation failed: %s - %s", path, e)
             if (
                 e.context.get("reason")
                 == SecurityErrorReasons.PATH_OUTSIDE_ALLOWED
@@ -89,16 +111,22 @@ def validate_path_mapping(
 
     # Check path existence and type
     if not path.exists():
+        logger.error("Path does not exist: %s", path)
         if is_dir:
             raise DirectoryNotFoundError(f"Directory not found: {path}")
-        raise FileNotFoundError(f"File not found: {path}")
+        raise OstructFileNotFoundError(f"File not found: {path}")
 
     # Check path type
     if is_dir and not path.is_dir():
+        logger.error("Path exists but is not a directory: %s", path)
         raise DirectoryNotFoundError(
             f"Path exists but is not a directory: {path}"
         )
     elif not is_dir and not path.is_file():
-        raise FileNotFoundError(f"Path exists but is not a file: {path}")
+        logger.error("Path exists but is not a file: %s", path)
+        raise OstructFileNotFoundError(
+            f"Path exists but is not a file: {path}"
+        )
 
+    logger.debug("Path validation successful: %s -> %s", name, path)
     return name, str(path)

ostruct/cli/security/allowed_checker.py

@@ -25,6 +25,9 @@ def is_path_in_allowed_dirs(
     Returns:
         True if path is within one of the allowed directories; False otherwise.
 
+    Raises:
+        TypeError: If path is None or not a string/Path object.
+
     Example:
         >>> allowed = [Path("/base"), Path("/tmp")]
         >>> is_path_in_allowed_dirs("/base/file.txt", allowed)
@@ -32,6 +35,11 @@ def is_path_in_allowed_dirs(
         >>> is_path_in_allowed_dirs("/etc/passwd", allowed)
         False
     """
+    if path is None:
+        raise TypeError("path must be a string or Path object")
+    if not isinstance(path, (str, Path)):
+        raise TypeError("path must be a string or Path object")
+
     norm_path = normalize_path(path)
     norm_allowed = [normalize_path(d) for d in allowed_dirs]
 

ostruct/cli/security/base.py

@@ -0,0 +1,46 @@
+"""Base class for security-related errors."""
+
+from typing import Any, Dict, Optional
+
+from ostruct.cli.base_errors import CLIError
+from ostruct.cli.exit_codes import ExitCode
+
+
+class SecurityErrorBase(CLIError):
+    """Base class for security-related errors."""
+
+    def __init__(
+        self,
+        message: str,
+        context: Optional[Dict[str, Any]] = None,
+        details: Optional[str] = None,
+        has_been_logged: bool = False,
+    ) -> None:
+        """Initialize security error.
+
+        Args:
+            message: The error message.
+            context: Additional context for the error.
+            details: Detailed explanation of the error.
+            has_been_logged: Whether the error has been logged.
+        """
+        if context is None:
+            context = {}
+        context["category"] = "security"
+        super().__init__(
+            message,
+            context=context,
+            exit_code=ExitCode.SECURITY_ERROR,
+            details=details,
+        )
+        self._has_been_logged = has_been_logged
+
+    @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

ostruct/cli/security/errors.py

@@ -6,121 +6,64 @@ the security modules.
 
 from typing import Any, Dict, List, Optional
 
+from .base import SecurityErrorBase
 
-class PathSecurityError(Exception):
-    """Base exception for security-related errors.
 
-    This class provides rich error information for security-related issues,
-    including context and error wrapping capabilities.
-    """
+class PathSecurityError(SecurityErrorBase):
+    """Security error for path-related issues."""
 
     def __init__(
         self,
         message: str,
-        path: str = "",
+        path: Optional[str] = None,
         context: Optional[Dict[str, Any]] = None,
+        details: Optional[str] = None,
         error_logged: bool = False,
+        wrapped: bool = False,
     ) -> None:
         """Initialize the 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 already been logged.
+            context: Additional context for the error.
+            details: Detailed explanation of the error.
+            error_logged: Whether the error has been logged.
+            wrapped: Whether this is a wrapped error.
         """
-        super().__init__(message)
-        self.path = path
-        self.context = context or {}
-        self._error_logged = error_logged
-        self._wrapped = False
-
-    def __str__(self) -> str:
-        """Format the error message with context if available."""
-        msg = super().__str__()
-
-        # Add expanded path information if available
-        if self.context:
-            if (
-                "original_path" in self.context
-                and "expanded_path" in self.context
-            ):
-                msg = (
-                    f"{msg}\n"
-                    f"Original path: {self.context['original_path']}\n"
-                    f"Expanded path: {self.context['expanded_path']}"
-                )
-            if "base_dir" in self.context:
-                msg = f"{msg}\nBase directory: {self.context['base_dir']}"
-            if "allowed_dirs" in self.context:
-                msg = f"{msg}\nAllowed directories: {self.context['allowed_dirs']!r}"
-
-        return msg
+        if context is None:
+            context = {}
+        if path is not None:
+            context["path"] = path
+        if details is None:
+            details = "The specified path violates security constraints"
+            context["troubleshooting"] = [
+                "Check if the path is within allowed directories",
+                "Use --allowed-dir to specify additional allowed directories",
+                "Verify path permissions",
+            ]
+        self._wrapped = wrapped
+        super().__init__(
+            message,
+            context=context,
+            details=details,
+            has_been_logged=error_logged,
+        )
 
     @property
-    def has_been_logged(self) -> bool:
-        """Whether this error has been logged."""
-        return self._error_logged
-
-    @has_been_logged.setter
-    def has_been_logged(self, value: bool) -> None:
-        """Set whether this error has been logged."""
-        self._error_logged = value
+    def error_logged(self) -> bool:
+        """Alias for has_been_logged for backward compatibility."""
+        return self.has_been_logged
 
     @property
     def wrapped(self) -> bool:
-        """Whether this error is wrapping another error."""
+        """Whether this is a wrapped error."""
         return self._wrapped
 
-    def format_with_context(
-        self,
-        original_path: str,
-        expanded_path: str,
-        base_dir: str,
-        allowed_dirs: List[str],
-    ) -> str:
-        """Format the error message with additional context.
-
-        Args:
-            original_path: The original path that caused the error
-            expanded_path: The expanded/absolute path
-            base_dir: The base directory for security checks
-            allowed_dirs: List of allowed directories
-
-        Returns:
-            A formatted error message with context
-        """
-        lines = [
-            str(self),
-            f"Original path: {original_path}",
-            f"Expanded path: {expanded_path}",
-            f"Base directory: {base_dir}",
-            f"Allowed directories: {allowed_dirs}",
-            "Use --allowed-dir to add more allowed directories",
-        ]
-        return "\n".join(lines)
-
-    @classmethod
-    def wrap_error(
-        cls, message: str, original: "PathSecurityError"
-    ) -> "PathSecurityError":
-        """Wrap an existing error with additional context.
-
-        Args:
-            message: The new error message
-            original: The original error to wrap
-
-        Returns:
-            A new PathSecurityError instance wrapping the original
-        """
-        wrapped = cls(
-            f"{message}: {str(original)}",
-            path=original.path,
-            context=original.context,
-            error_logged=original.has_been_logged,
-        )
-        wrapped._wrapped = True
-        return wrapped
+    @property
+    def details(self) -> str:
+        """Get the detailed explanation of the error."""
+        return self.details
 
     @classmethod
     def from_expanded_paths(
@@ -131,32 +74,69 @@ class PathSecurityError(Exception):
         allowed_dirs: List[str],
         error_logged: bool = False,
     ) -> "PathSecurityError":
-        """Create an error instance with expanded path information.
+        """Create an error from expanded paths.
 
         Args:
-            original_path: The original path that caused the error
-            expanded_path: The expanded/absolute path
-            base_dir: The base directory for security checks
-            allowed_dirs: List of allowed directories
-            error_logged: Whether this error has already been logged
+            original_path: The original path.
+            expanded_path: The expanded path.
+            base_dir: The base directory.
+            allowed_dirs: List of allowed directories.
+            error_logged: Whether the error has been logged.
 
         Returns:
-            A new PathSecurityError instance with expanded path context
+            A new PathSecurityError instance.
         """
-        message = f"Path '{original_path}' is outside the base directory and not in allowed directories"
         context = {
             "original_path": original_path,
             "expanded_path": expanded_path,
             "base_dir": base_dir,
             "allowed_dirs": allowed_dirs,
+            "reason": SecurityErrorReasons.PATH_OUTSIDE_ALLOWED,
+            "troubleshooting": [
+                "Check if the path is within allowed directories",
+                f"Ensure the path is within base directory: {base_dir}",
+                f"Current allowed directories: {', '.join(allowed_dirs)}",
+            ],
         }
         return cls(
-            message,
-            path=original_path,
+            "Access denied",
             context=context,
+            details="Path is outside allowed directories",
             error_logged=error_logged,
         )
 
+    @classmethod
+    def wrap_error(
+        cls, message: str, original_error: Exception
+    ) -> "PathSecurityError":
+        """Wrap another error with a security error.
+
+        Args:
+            message: The security error message.
+            original_error: The original error to wrap.
+
+        Returns:
+            A new PathSecurityError instance.
+        """
+        context = {
+            "wrapped_error": original_error.__class__.__name__,
+            "original_message": str(original_error),
+            "wrapped": True,
+            "troubleshooting": [
+                "Check if the path is within allowed directories",
+                "Verify path permissions",
+                "Check if the original error has been resolved",
+            ],
+        }
+        if hasattr(original_error, "context"):
+            context.update(original_error.context)
+        return cls(
+            message,
+            context=context,
+            wrapped=True,
+            error_logged=getattr(original_error, "error_logged", False),
+        )
+
 
 class DirectoryNotFoundError(PathSecurityError):
     """Raised when a directory that is expected to exist does not."""