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

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."""

ostruct/cli/security/security_manager.py

@@ -15,6 +15,8 @@ from contextlib import contextmanager
 from pathlib import Path
 from typing import Generator, List, Optional, Union
 
+from ostruct.cli.errors import OstructFileNotFoundError
+
 from .allowed_checker import is_path_in_allowed_dirs
 from .case_manager import CaseManager
 from .errors import (
@@ -200,24 +202,32 @@ class SecurityManager:
             PathSecurityError: If the path fails security validation
             FileNotFoundError: If the file doesn't exist (only checked after security validation)
         """
+        logger.debug("Validating path: %s", path)
+
         # First normalize the path
         norm_path = normalize_path(path)
+        logger.debug("Normalized path: %s", norm_path)
 
         # Handle symlinks first - delegate to symlink_resolver
         if norm_path.is_symlink():
+            logger.debug("Path is a symlink, resolving: %s", norm_path)
             try:
-                return _resolve_symlink(
+                resolved = _resolve_symlink(
                     norm_path,
                     self._max_symlink_depth,
                     self._allowed_dirs,
                 )
+                logger.debug("Resolved symlink to: %s", resolved)
+                return resolved
             except RuntimeError as e:
                 if "Symlink loop" in str(e):
+                    logger.error("Symlink loop detected: %s", path)
                     raise PathSecurityError(
                         "Symlink security violation: loop detected",
                         path=str(path),
                         context={"reason": SecurityErrorReasons.SYMLINK_LOOP},
                     ) from e
+                logger.error("Failed to resolve symlink: %s - %s", path, e)
                 raise PathSecurityError(
                     f"Symlink security violation: failed to resolve symlink - {e}",
                     path=str(path),
@@ -225,10 +235,13 @@ class SecurityManager:
                 ) from e
 
         # For non-symlinks, just check if the normalized path is allowed
+        logger.debug("Checking if path is allowed: %s", norm_path)
         if not self.is_path_allowed(norm_path):
             logger.error(
-                "Security violation: Path %s is outside allowed directories",
+                "Security violation: Path %s is outside allowed directories (base_dir=%s, allowed_dirs=%s)",
                 path,
+                self._base_dir,
+                self._allowed_dirs,
             )
             raise PathSecurityError(
                 (
@@ -244,12 +257,12 @@ class SecurityManager:
             )
 
         # Only check existence after security validation passes
+        logger.debug("Checking if path exists: %s", norm_path)
         if not norm_path.exists():
             logger.debug("Path allowed but not found: %s", norm_path)
-            raise FileNotFoundError(
-                f"File not found: {os.path.basename(str(path))}"
-            )
+            raise OstructFileNotFoundError(str(path))
 
+        logger.debug("Path validation successful: %s", norm_path)
         return norm_path
 
     def resolve_path(self, path: Union[str, Path]) -> Path:
@@ -275,7 +288,7 @@ class SecurityManager:
             if self._allow_temp_paths and self.is_temp_path(norm_path):
                 logger.debug("Allowing temp path: %s", norm_path)
                 if not norm_path.exists():
-                    raise FileNotFoundError(f"File not found: {path}")
+                    raise OstructFileNotFoundError(f"File not found: {path}")
                 return norm_path
 
             # Handle symlinks with security checks
@@ -296,7 +309,7 @@ class SecurityManager:
                     elif reason == SecurityErrorReasons.SYMLINK_BROKEN:
                         msg = f"Broken symlink: {e.context['source']} -> {e.context['target']}"
                         logger.debug(msg)
-                        raise FileNotFoundError(msg) from e
+                        raise OstructFileNotFoundError(msg) from e
                     # Any other security errors propagate unchanged
                     raise
 
@@ -318,12 +331,12 @@ class SecurityManager:
 
             # Only check existence after security validation
             if not norm_path.exists():
-                raise FileNotFoundError(f"File not found: {path}")
+                raise OstructFileNotFoundError(f"File not found: {path}")
 
             return norm_path
 
         except OSError as e:
-            if isinstance(e, FileNotFoundError):
+            if isinstance(e, OstructFileNotFoundError):
                 raise
             logger.error("Error resolving path: %s - %s", path, e)
             raise PathSecurityError(

ostruct/cli/serialization.py

@@ -0,0 +1,25 @@
+"""Serialization utilities for CLI logging."""
+
+import json
+from typing import Any, Dict
+
+
+class LogSerializer:
+    """Utility class for serializing log data."""
+
+    @staticmethod
+    def serialize_log_extra(extra: Dict[str, Any]) -> str:
+        """Serialize extra log data to a formatted string.
+
+        Args:
+            extra: Dictionary of extra log data
+
+        Returns:
+            Formatted string representation of the extra data
+        """
+        try:
+            # Try to serialize with nice formatting
+            return json.dumps(extra, indent=2, default=str)
+        except Exception:
+            # Fall back to basic string representation if JSON fails
+            return str(extra)

ostruct/cli/template_filters.py

@@ -10,7 +10,7 @@ from collections import Counter
 from typing import Any, Dict, List, Optional, Sequence, TypeVar, Union
 
 import tiktoken
-from jinja2 import Environment
+from jinja2 import Environment, pass_context
 from pygments import highlight
 from pygments.formatters import HtmlFormatter, NullFormatter, TerminalFormatter
 from pygments.lexers import TextLexer, get_lexer_by_name, guess_lexer
@@ -178,10 +178,12 @@ def format_error(e: Exception) -> str:
     return f"{type(e).__name__}: {str(e)}"
 
 
-def estimate_tokens(text: str) -> int:
+@pass_context
+def estimate_tokens(context: Any, text: str) -> int:
     """Estimate number of tokens in text."""
     try:
-        encoding = tiktoken.encoding_for_model("gpt-4")
+        # Use o200k_base encoding for token estimation
+        encoding = tiktoken.get_encoding("o200k_base")
         return len(encoding.encode(str(text)))
     except Exception as e:
         logger.warning(f"Failed to estimate tokens: {e}")

ostruct/cli/template_rendering.py

@@ -61,8 +61,9 @@ from typing import Any, Dict, List, Optional, Union
 import jinja2
 from jinja2 import Environment
 
-from .errors import TemplateValidationError
+from .errors import TaskTemplateVariableError, TemplateValidationError
 from .file_utils import FileInfo
+from .progress import ProgressContext
 from .template_env import create_jinja_env
 from .template_schema import DotDict, StdinProxy
 
@@ -92,23 +93,23 @@ TemplateContextValue = Union[
 def render_template(
     template_str: str,
     context: Dict[str, Any],
-    jinja_env: Optional[Environment] = None,
-    progress_enabled: bool = True,
+    env: Optional[Environment] = None,
+    progress: Optional[ProgressContext] = None,
 ) -> str:
-    """Render a task template with the given context.
+    """Render a template with the given context.
 
     Args:
-        template_str: Task template string or path to task template file
-        context: Task template variables
-        jinja_env: Optional Jinja2 environment to use
-        progress_enabled: Whether to show progress indicators
+        template_str: Template string to render
+        context: Context dictionary for template variables
+        env: Optional Jinja2 environment to use
+        progress: Optional progress bar to update
 
     Returns:
-        Rendered task template string
+        str: The rendered template string
 
     Raises:
-        TemplateValidationError: If task template cannot be loaded or rendered. The original error
-                  will be chained using `from` for proper error context.
+        TaskTemplateVariableError: If template variables are undefined
+        TemplateValidationError: If template rendering fails for other reasons
     """
     from .progress import (  # Import here to avoid circular dependency
         ProgressContext,
@@ -116,16 +117,14 @@ def render_template(
 
     with ProgressContext(
         description="Rendering task template",
-        level="basic" if progress_enabled else "none",
+        level="basic" if progress else "none",
     ) as progress:
         try:
             if progress:
                 progress.update(1)  # Update progress for setup
 
-            if jinja_env is None:
-                jinja_env = create_jinja_env(
-                    loader=jinja2.FileSystemLoader(".")
-                )
+            if env is None:
+                env = create_jinja_env(loader=jinja2.FileSystemLoader("."))
 
             logger.debug("=== Raw Input ===")
             logger.debug(
@@ -154,7 +153,7 @@ def render_template(
             # Wrap JSON variables in DotDict and handle special cases
             wrapped_context: Dict[str, TemplateContextValue] = {}
             for key, value in context.items():
-                if isinstance(value, dict):
+                if isinstance(value, dict) and not isinstance(value, DotDict):
                     wrapped_context[key] = DotDict(value)
                 else:
                     wrapped_context[key] = value
@@ -188,7 +187,7 @@ def render_template(
                         f"Task template file not found: {template_str}"
                     )
                 try:
-                    template = jinja_env.get_template(template_str)
+                    template = env.get_template(template_str)
                 except jinja2.TemplateNotFound as e:
                     raise TemplateValidationError(
                         f"Task template file not found: {e.name}"
@@ -199,10 +198,10 @@ def render_template(
                     template_str,
                 )
                 try:
-                    template = jinja_env.from_string(template_str)
+                    template = env.from_string(template_str)
 
                     # Add debug log for loop rendering
-                    def debug_file_render(f: FileInfo) -> str:
+                    def debug_file_render(f: FileInfo) -> Any:
                         logger.info("Rendering file: %s", f.path)
                         return ""
 
@@ -292,6 +291,10 @@ def render_template(
                             "  %s: %s (%r)", key, type(value).__name__, value
                         )
                 result = template.render(**wrapped_context)
+                if not isinstance(result, str):
+                    raise TemplateValidationError(
+                        f"Template rendered to non-string type: {type(result)}"
+                    )
                 logger.info(
                     "Template render result (first 100 chars): %r",
                     result[:100],
@@ -302,7 +305,17 @@ def render_template(
                 )
                 if progress:
                     progress.update(1)
-                return result  # type: ignore[no-any-return]
+                return result
+            except jinja2.UndefinedError as e:
+                # Extract variable name from error message
+                var_name = str(e).split("'")[1]
+                error_msg = (
+                    f"Missing required template variable: {var_name}\n"
+                    f"Available variables: {', '.join(sorted(context.keys()))}\n"
+                    "To fix this, please provide the variable using:\n"
+                    f"  -V {var_name}='value'"
+                )
+                raise TaskTemplateVariableError(error_msg) from e
             except (jinja2.TemplateError, Exception) as e:
                 logger.error("Template rendering failed: %s", str(e))
                 raise TemplateValidationError(
@@ -336,4 +349,15 @@ def render_template_file(
     """
     with open(template_path, "r", encoding="utf-8") as f:
         template_str = f.read()
-    return render_template(template_str, context, jinja_env, progress_enabled)
+
+    # Create a progress context if enabled
+    progress = (
+        ProgressContext(
+            description="Rendering template file",
+            level="basic" if progress_enabled else "none",
+        )
+        if progress_enabled
+        else None
+    )
+
+    return render_template(template_str, context, jinja_env, progress)

ostruct/cli/template_utils.py

@@ -9,10 +9,11 @@ It re-exports the public APIs from specialized modules:
 - template_io: File I/O operations and metadata extraction
 """
 
+import logging
 from typing import Any, Dict, List, Optional, Set
 
 import jsonschema
-from jinja2 import Environment, meta
+from jinja2 import Environment, TemplateSyntaxError, meta
 from jinja2.nodes import Node
 
 from .errors import (
@@ -35,6 +36,8 @@ from .template_schema import (
 )
 from .template_validation import SafeUndefined, validate_template_placeholders
 
+logger = logging.getLogger(__name__)
+
 
 # Custom error classes
 class TemplateMetadataError(TaskTemplateError):
@@ -118,8 +121,13 @@ def find_all_template_variables(
     if env is None:
         env = Environment(undefined=SafeUndefined)
 
-    # Parse template
-    ast = env.parse(template)
+    try:
+        ast = env.parse(template)
+    except TemplateSyntaxError as e:
+        logger.error("Failed to parse template: %s", str(e))
+        return set()  # Return empty set on parse error
+
+    variables: Set[str] = set()
 
     # Find all variables in this template
     variables = meta.find_undeclared_variables(ast)
@@ -252,7 +260,7 @@ def find_all_template_variables(
                 visit_nodes(node.else_)
 
     visit_nodes(ast.body)
-    return variables  # type: ignore[no-any-return]
+    return variables
 
 
 __all__ = [

ostruct/cli/template_validation.py

@@ -67,7 +67,7 @@ from jinja2 import meta
 from jinja2.nodes import For, Name, Node
 
 from . import template_filters
-from .errors import TemplateValidationError
+from .errors import TaskTemplateVariableError, TemplateValidationError
 from .template_env import create_jinja_env
 from .template_schema import (
     DictProxy,
@@ -160,7 +160,8 @@ def validate_template_placeholders(
         template_context: Optional context to validate against
 
     Raises:
-        TemplateValidationError: If any placeholders are invalid
+        TaskTemplateVariableError: If any variables are undefined
+        TemplateValidationError: If template validation fails for other reasons
     """
     logger = logging.getLogger(__name__)
 
@@ -309,10 +310,15 @@ def validate_template_placeholders(
         }
 
         if missing:
-            raise TemplateValidationError(
-                f"Task template uses undefined variables: {', '.join(sorted(missing))}. "
-                f"Available variables: {', '.join(sorted(available_vars))}"
+            # Create a more user-friendly error message
+            error_msg = (
+                f"Missing required template variable(s): {', '.join(sorted(missing))}\n"
+                f"Available variables: {', '.join(sorted(available_vars))}\n"
+                "To fix this, please provide the missing variable(s) using:\n"
             )
+            for var in sorted(missing):
+                error_msg += f"  -V {var}='value'\n"
+            raise TaskTemplateVariableError(error_msg)
 
         logger.debug(
             "Before create_validation_context - available_vars type: %s, value: %s",
@@ -336,8 +342,17 @@ def validate_template_placeholders(
         try:
             env.from_string(template).render(validation_context)
         except jinja2.UndefinedError as e:
-            # Convert Jinja2 undefined errors to our own ValueError
-            raise TemplateValidationError(str(e))
+            # Convert Jinja2 undefined errors to TaskTemplateVariableError with helpful message
+            var_name = str(e).split("'")[
+                1
+            ]  # Extract variable name from error message
+            error_msg = (
+                f"Missing required template variable: {var_name}\n"
+                f"Available variables: {', '.join(sorted(available_vars))}\n"
+                "To fix this, please provide the variable using:\n"
+                f"  -V {var_name}='value'"
+            )
+            raise TaskTemplateVariableError(error_msg) from e
         except ValueError as e:
             # Convert validation errors from template_schema to TemplateValidationError
             raise TemplateValidationError(str(e))
@@ -348,10 +363,13 @@ def validate_template_placeholders(
             raise
 
     except jinja2.TemplateSyntaxError as e:
-        # Convert Jinja2 syntax errors to our own ValueError
+        # Convert Jinja2 syntax errors to TemplateValidationError
         raise TemplateValidationError(
             f"Invalid task template syntax: {str(e)}"
         )
+    except (TaskTemplateVariableError, TemplateValidationError):
+        # Re-raise these without wrapping
+        raise
     except Exception as e:
         logger.error("Unexpected error during template validation: %s", str(e))
         raise