ostruct-cli 0.7.2__py3-none-any.whl → 0.8.0__py3-none-any.whl

ostruct/cli/file_info.py

@@ -24,6 +24,7 @@ class FileInfo:
         content: Optional cached content
         encoding: Optional cached encoding
         hash_value: Optional cached hash value
+        routing_type: How the file was routed (e.g., 'template', 'code-interpreter')
     """
 
     def __init__(
@@ -33,6 +34,7 @@ class FileInfo:
         content: Optional[str] = None,
         encoding: Optional[str] = None,
         hash_value: Optional[str] = None,
+        routing_type: Optional[str] = None,
     ) -> None:
         """Initialize FileInfo instance.
 
@@ -42,19 +44,13 @@ class FileInfo:
             content: Optional cached content
             encoding: Optional cached encoding
             hash_value: Optional cached hash value
+            routing_type: How the file was routed (e.g., 'template', 'code-interpreter')
 
         Raises:
             FileNotFoundError: If the file does not exist
             PathSecurityError: If the path is not allowed
             PermissionError: If access is denied
         """
-        logger.debug("Creating FileInfo for path: %s", path)
-
-        # Validate path
-        if not path:
-            raise ValueError("Path cannot be empty")
-
-        # Initialize private attributes
         self.__path = str(path)
         self.__security_manager = security_manager
         self.__content = content
@@ -62,6 +58,17 @@ class FileInfo:
         self.__hash = hash_value
         self.__size: Optional[int] = None
         self.__mtime: Optional[float] = None
+        self.routing_type = routing_type
+
+        logger.debug(
+            "Creating FileInfo for path: %s, routing_type: %s",
+            path,
+            self.routing_type,
+        )
+
+        # Validate path
+        if not path:
+            raise ValueError("Path cannot be empty")
 
         try:
             # This will raise PathSecurityError if path is not allowed
@@ -125,6 +132,23 @@ class FileInfo:
                 f"Permission denied: {os.path.basename(str(path))}"
             ) from e
 
+        # Add warning for large template-only files accessed via .content
+        # Check if routing_type is 'template' or if it's part of a legacy -f/-d mapping
+        # For simplicity now, let's assume if routing_type is None it could be legacy template
+        is_template_routed = (
+            self.routing_type == "template" or self.routing_type is None
+        )
+        if (
+            is_template_routed and self.size and self.size > 100 * 1024
+        ):  # 100KB threshold
+            logger.warning(
+                f"File '{self.path}' ({self.size / 1024:.1f}KB) was routed for template-only access "
+                f"but its .content is being accessed. This will include the entire file content "
+                f"in the prompt sent to the AI. For large files intended for analysis or search, "
+                f"consider using -fc (Code Interpreter) or -fs (File Search) to optimize token usage, "
+                f"cost, and avoid exceeding model context limits."
+            )
+
     @property
     def path(self) -> str:
         """Get the path relative to security manager's base directory.
@@ -356,13 +380,17 @@ class FileInfo:
 
     @classmethod
     def from_path(
-        cls, path: str, security_manager: SecurityManager
+        cls,
+        path: str,
+        security_manager: SecurityManager,
+        routing_type: Optional[str] = None,
     ) -> "FileInfo":
         """Create FileInfo instance from path.
 
         Args:
             path: Path to file
             security_manager: Security manager for path validation
+            routing_type: How the file was routed (e.g., 'template', 'code-interpreter')
 
         Returns:
             FileInfo instance
@@ -371,7 +399,7 @@ class FileInfo:
             FileNotFoundError: If file does not exist
             PathSecurityError: If path is not allowed
         """
-        return cls(path, security_manager)
+        return cls(path, security_manager, routing_type=routing_type)
 
     def __str__(self) -> str:
         """String representation showing path."""
@@ -391,6 +419,11 @@ class FileInfo:
 
         Internal methods can modify private attributes, but external access is prevented.
         """
+        # Allow setting routing_type if it's not already set (i.e., during __init__)
+        if name == "routing_type" and not hasattr(self, name):
+            object.__setattr__(self, name, value)
+            return
+
         # Allow setting private attributes from internal methods
         if name.startswith("_FileInfo__") and self._is_internal_call():
             object.__setattr__(self, name, value)

ostruct/cli/file_list.py

@@ -2,7 +2,15 @@
 
 import logging
 import threading
-from typing import Iterable, Iterator, List, SupportsIndex, Union, overload
+from typing import (
+    Iterable,
+    Iterator,
+    List,
+    Optional,
+    SupportsIndex,
+    Union,
+    overload,
+)
 
 from .file_info import FileInfo
 
@@ -12,12 +20,15 @@ logger = logging.getLogger(__name__)
 
 
 class FileInfoList(List[FileInfo]):
-    """List of FileInfo objects with smart content access.
+    """List of FileInfo objects with strict single-file content access.
 
     This class extends List[FileInfo] to provide convenient access to file contents
-    and metadata. When the list contains exactly one file from a single file mapping,
-    properties like content return the value directly. For multiple files or directory
-    mappings, properties return a list of values.
+    and metadata. Properties like content, path, name, etc. are designed for single-file
+    access only and will raise ValueError for multiple files or directory mappings.
+
+    This prevents accidental data exposure and template errors by requiring explicit
+    handling of multi-file scenarios through indexing (files[0].content) or the
+    |single filter (files|single.content).
 
     This class is thread-safe. All operations that access or modify the internal list
     are protected by a reentrant lock (RLock). This allows nested method calls while
@@ -30,195 +41,383 @@ class FileInfoList(List[FileInfo]):
             files = FileInfoList([file_info], from_dir=False)
             content = files.content  # Returns "file contents"
 
-        Multiple files or directory (--files or --dir):
+        Multiple files or directory (raises error):
             files = FileInfoList([file1, file2])  # or FileInfoList([file1], from_dir=True)
-            content = files.content  # Returns ["contents1", "contents2"] or ["contents1"]
+            content = files.content  # Raises ValueError with helpful message
 
-        Backward compatibility:
-            content = files[0].content  # Still works
+        Safe multi-file access:
+            content = files[0].content  # Access first file explicitly
+            content = files|single.content  # Use |single filter for validation
 
     Properties:
-        content: File content(s) - string for single file mapping, list for multiple files or directory
-        path: File path(s)
-        abs_path: Absolute file path(s)
-        size: File size(s) in bytes
+        content: File content - only for single file from file mapping (not directory)
+        path: File path - only for single file from file mapping
+        abs_path: Absolute file path - only for single file from file mapping
+        size: File size in bytes - only for single file from file mapping
+        name: Filename without directory path - only for single file from file mapping
+        names: Always returns list of all filenames (safe for multi-file access)
 
     Raises:
-        ValueError: When accessing properties on an empty list
+        ValueError: When accessing scalar properties on empty list, multiple files, or directory mappings
     """
 
-    def __init__(self, files: List[FileInfo], from_dir: bool = False) -> None:
+    def __init__(
+        self,
+        files: List[FileInfo],
+        from_dir: bool = False,
+        var_alias: Optional[str] = None,
+    ) -> None:
         """Initialize FileInfoList.
 
         Args:
             files: List of FileInfo objects
             from_dir: Whether this list was created from a directory mapping
+            var_alias: Variable name used in template (for error messages)
         """
         logger.debug(
-            "Creating FileInfoList with %d files, from_dir=%s",
+            "Creating FileInfoList with %d files, from_dir=%s, var_alias=%s",
             len(files),
             from_dir,
+            var_alias,
         )
         self._lock = threading.RLock()  # Use RLock for nested method calls
         super().__init__(files)
         self._from_dir = from_dir
+        self._var_alias = var_alias
 
     @property
-    def content(self) -> Union[str, List[str]]:
-        """Get the content of the file(s).
+    def content(self) -> str:
+        """Get the content of a single file.
 
         Returns:
-            Union[str, List[str]]: For a single file from file mapping, returns its content as a string.
-                                  For multiple files, directory mapping, or empty list, returns a list of contents.
+            str: Content of the single file from file mapping.
+
+        Raises:
+            ValueError: If the list is empty or contains multiple files.
         """
         # Take snapshot under lock
         with self._lock:
             if not self:
-                logger.debug("FileInfoList.content called but list is empty")
-                return []
+                var_name = self._var_alias or "file_list"
+                raise ValueError(
+                    f"No files in '{var_name}'. Cannot access .content property."
+                )
 
-            # Make a copy of the files we need to access
-            if len(self) == 1 and not self._from_dir:
-                file_info = self[0]
-                is_single = True
-            else:
-                files = list(self)
-                is_single = False
+            # Check for multiple files or directory mapping
+            if len(self) > 1:
+                var_name = self._var_alias or "file_list"
+                raise ValueError(
+                    f"'{var_name}' contains {len(self)} files. "
+                    f"Use '{{{{ {var_name}[0].content }}}}' for the first file, "
+                    f"'{{{{ {var_name}|single.content }}}}' if expecting exactly one file, "
+                    f"or loop over files with '{{%% for file in {var_name} %%}}{{{{ file.content }}}}{{%% endfor %%}}'."
+                )
 
-        # Access file contents outside lock to prevent deadlocks
-        try:
-            if is_single:
-                logger.debug(
-                    "FileInfoList.content returning single file content (not from dir)"
+            if self._from_dir:
+                var_name = self._var_alias or "file_list"
+                raise ValueError(
+                    f"'{var_name}' contains files from directory mapping. "
+                    f"Use '{{{{ {var_name}[0].content }}}}' for the first file, "
+                    f"'{{{{ {var_name}|single.content }}}}' if expecting exactly one file, "
+                    f"or loop over files with '{{%% for file in {var_name} %%}}{{{{ file.content }}}}{{%% endfor %%}}'."
                 )
-                return file_info.content
 
+            # Single file from file mapping
+            file_info = self[0]
+
+        # Access file content outside lock to prevent deadlocks
+        try:
             logger.debug(
-                "FileInfoList.content returning list of %d contents (from_dir=%s)",
-                len(files),
-                self._from_dir,
+                "FileInfoList.content returning single file content (not from dir)"
             )
-            return [f.content for f in files]
+            return file_info.content
         except Exception as e:
             logger.error("Error accessing file content: %s", e)
             raise
 
     @property
-    def path(self) -> Union[str, List[str]]:
-        """Get the path of the file(s).
+    def path(self) -> str:
+        """Get the path of a single file.
 
         Returns:
-            Union[str, List[str]]: For a single file from file mapping, returns its path as a string.
-                                  For multiple files, directory mapping, or empty list, returns a list of paths.
+            str: Path of the single file from file mapping.
+
+        Raises:
+            ValueError: If the list is empty or contains multiple files.
         """
         # First get a snapshot of the list state under the lock
         with self._lock:
             if not self:
-                return []
-            if len(self) == 1 and not self._from_dir:
-                file_info = self[0]
-                is_single = True
-            else:
-                files = list(self)
-                is_single = False
+                var_name = self._var_alias or "file_list"
+                raise ValueError(
+                    f"No files in '{var_name}'. Cannot access .path property."
+                )
 
-        # Now access file paths outside the lock
+            # Check for multiple files or directory mapping
+            if len(self) > 1:
+                var_name = self._var_alias or "file_list"
+                raise ValueError(
+                    f"'{var_name}' contains {len(self)} files. "
+                    f"Use '{{{{ {var_name}[0].path }}}}' for the first file, "
+                    f"'{{{{ {var_name}|single.path }}}}' if expecting exactly one file, "
+                    f"or loop over files with '{{%% for file in {var_name} %%}}{{{{ file.path }}}}{{%% endfor %%}}'."
+                )
+
+            if self._from_dir:
+                var_name = self._var_alias or "file_list"
+                raise ValueError(
+                    f"'{var_name}' contains files from directory mapping. "
+                    f"Use '{{{{ {var_name}[0].path }}}}' for the first file, "
+                    f"'{{{{ {var_name}|single.path }}}}' if expecting exactly one file, "
+                    f"or loop over files with '{{%% for file in {var_name} %%}}{{{{ file.path }}}}{{%% endfor %%}}'."
+                )
+
+            # Single file from file mapping
+            file_info = self[0]
+
+        # Now access file path outside the lock
         try:
-            if is_single:
-                return file_info.path
-            return [f.path for f in files]
+            return file_info.path
         except Exception as e:
             logger.error("Error accessing file path: %s", e)
             raise
 
     @property
-    def abs_path(self) -> Union[str, List[str]]:
-        """Get the absolute path of the file(s).
+    def abs_path(self) -> str:
+        """Get the absolute path of a single file.
 
         Returns:
-            Union[str, List[str]]: For a single file from file mapping, returns its absolute path as a string.
-                                  For multiple files or directory mapping, returns a list of absolute paths.
+            str: Absolute path of the single file from file mapping.
 
         Raises:
-            ValueError: If the list is empty
+            ValueError: If the list is empty or contains multiple files.
         """
         # First get a snapshot of the list state under the lock
         with self._lock:
             if not self:
-                raise ValueError("No files in FileInfoList")
-            if len(self) == 1 and not self._from_dir:
-                file_info = self[0]
-                is_single = True
-            else:
-                files = list(self)
-                is_single = False
+                var_name = self._var_alias or "file_list"
+                raise ValueError(
+                    f"No files in '{var_name}'. Cannot access .abs_path property."
+                )
 
-        # Now access file paths outside the lock
+            # Check for multiple files or directory mapping
+            if len(self) > 1:
+                var_name = self._var_alias or "file_list"
+                raise ValueError(
+                    f"'{var_name}' contains {len(self)} files. "
+                    f"Use '{{{{ {var_name}[0].abs_path }}}}' for the first file, "
+                    f"'{{{{ {var_name}|single.abs_path }}}}' if expecting exactly one file, "
+                    f"or loop over files with '{{%% for file in {var_name} %%}}{{{{ file.abs_path }}}}{{%% endfor %%}}'."
+                )
+
+            if self._from_dir:
+                var_name = self._var_alias or "file_list"
+                raise ValueError(
+                    f"'{var_name}' contains files from directory mapping. "
+                    f"Use '{{{{ {var_name}[0].abs_path }}}}' for the first file, "
+                    f"'{{{{ {var_name}|single.abs_path }}}}' if expecting exactly one file, "
+                    f"or loop over files with '{{%% for file in {var_name} %%}}{{{{ file.abs_path }}}}{{%% endfor %%}}'."
+                )
+
+            # Single file from file mapping
+            file_info = self[0]
+
+        # Now access file path outside the lock
         try:
-            if is_single:
-                return file_info.abs_path
-            return [f.abs_path for f in files]
+            return file_info.abs_path
         except Exception as e:
             logger.error("Error accessing absolute path: %s", e)
             raise
 
     @property
-    def size(self) -> Union[int, List[int]]:
-        """Get file size(s) in bytes.
+    def size(self) -> int:
+        """Get file size of a single file in bytes.
 
         Returns:
-            Union[int, List[int]]: For a single file from file mapping, returns its size in bytes.
-                                  For multiple files or directory mapping, returns a list of sizes.
+            int: Size of the single file from file mapping in bytes.
 
         Raises:
-            ValueError: If the list is empty or if any file size is None
+            ValueError: If the list is empty, contains multiple files, or file size is None.
         """
         # First get a snapshot of the list state under the lock
         with self._lock:
             if not self:
-                raise ValueError("No files in FileInfoList")
+                var_name = self._var_alias or "file_list"
+                raise ValueError(
+                    f"No files in '{var_name}'. Cannot access .size property."
+                )
 
-            # Make a copy of the files we need to access
-            if len(self) == 1 and not self._from_dir:
-                file_info = self[0]
-                is_single = True
-            else:
-                files = list(self)
-                is_single = False
+            # Check for multiple files or directory mapping
+            if len(self) > 1:
+                var_name = self._var_alias or "file_list"
+                raise ValueError(
+                    f"'{var_name}' contains {len(self)} files. "
+                    f"Use '{{{{ {var_name}[0].size }}}}' for the first file, "
+                    f"'{{{{ {var_name}|single.size }}}}' if expecting exactly one file, "
+                    f"or loop over files with '{{%% for file in {var_name} %%}}{{{{ file.size }}}}{{%% endfor %%}}'."
+                )
 
-        # Now access file sizes outside the lock
+            if self._from_dir:
+                var_name = self._var_alias or "file_list"
+                raise ValueError(
+                    f"'{var_name}' contains files from directory mapping. "
+                    f"Use '{{{{ {var_name}[0].size }}}}' for the first file, "
+                    f"'{{{{ {var_name}|single.size }}}}' if expecting exactly one file, "
+                    f"or loop over files with '{{%% for file in {var_name} %%}}{{{{ file.size }}}}{{%% endfor %%}}'."
+                )
+
+            # Single file from file mapping
+            file_info = self[0]
+
+        # Now access file size outside the lock
         try:
-            if is_single:
-                size = file_info.size
-                if size is None:
-                    raise ValueError(
-                        f"Could not get size for file: {file_info.path}"
-                    )
-                return size
-
-            sizes = []
-            for f in files:
-                size = f.size
-                if size is None:
-                    raise ValueError(f"Could not get size for file: {f.path}")
-                sizes.append(size)
-            return sizes
+            size = file_info.size
+            if size is None:
+                raise ValueError(
+                    f"Could not get size for file: {file_info.path}"
+                )
+            return size
         except Exception as e:
             logger.error("Error accessing file size: %s", e)
             raise
 
+    @property
+    def name(self) -> str:
+        """Get the filename of a single file without directory path.
+
+        Returns:
+            str: Name of the single file from file mapping.
+
+        Raises:
+            ValueError: If the list is empty or contains multiple files.
+        """
+        with self._lock:
+            if not self:
+                var_name = self._var_alias or "file_list"
+                raise ValueError(
+                    f"No files in '{var_name}'. Cannot access .name property."
+                )
+
+            # Check for multiple files or directory mapping
+            if len(self) > 1:
+                var_name = self._var_alias or "file_list"
+                raise ValueError(
+                    f"'{var_name}' contains {len(self)} files. "
+                    f"Use '{{{{ {var_name}[0].name }}}}' for the first file, "
+                    f"'{{{{ {var_name}|single.name }}}}' if expecting exactly one file, "
+                    f"or loop over files with '{{%% for file in {var_name} %%}}{{{{ file.name }}}}{{%% endfor %%}}'."
+                )
+
+            if self._from_dir:
+                var_name = self._var_alias or "file_list"
+                raise ValueError(
+                    f"'{var_name}' contains files from directory mapping. "
+                    f"Use '{{{{ {var_name}[0].name }}}}' for the first file, "
+                    f"'{{{{ {var_name}|single.name }}}}' if expecting exactly one file, "
+                    f"or loop over files with '{{%% for file in {var_name} %%}}{{{{ file.name }}}}{{%% endfor %%}}'."
+                )
+
+            # Single file from file mapping
+            return self[0].name
+
+    @property
+    def names(self) -> List[str]:
+        """Get all filenames as a list."""
+        with self._lock:
+            if not self:
+                return []
+            try:
+                return [f.name for f in self]
+            except Exception as e:
+                logger.error(
+                    f"Error accessing file names for .names property in '{self._var_alias or 'FileInfoList'}': {e}"
+                )
+                raise
+
+    def __getattr__(self, attr_name: str) -> None:
+        """Provide helpful error messages for FileInfo attributes accessed on multi-file lists."""
+        # Import here to avoid circular imports
+        try:
+            from .template_schema import FileInfoProxy
+
+            # Try to get _valid_attrs as a class attribute, but it's actually an instance attribute
+            # So we'll get an empty set and fall back to our hardcoded list
+            valid_attrs = getattr(FileInfoProxy, "_valid_attrs", None)
+            if not valid_attrs:
+                # Use the same attributes that FileInfoProxy uses
+                valid_attrs = {
+                    "name",
+                    "path",
+                    "content",
+                    "ext",
+                    "basename",
+                    "dirname",
+                    "abs_path",
+                    "exists",
+                    "is_file",
+                    "is_dir",
+                    "size",
+                    "mtime",
+                    "encoding",
+                    "hash",
+                    "extension",
+                    "parent",
+                    "stem",
+                    "suffix",
+                }
+        except ImportError:
+            # Fallback list of common FileInfo attributes
+            valid_attrs = {
+                "name",
+                "path",
+                "content",
+                "size",
+                "abs_path",
+                "exists",
+                "encoding",
+                "hash",
+            }
+
+        # Only provide enhanced errors for known FileInfo attributes
+        if attr_name in valid_attrs:
+            # Check if this is a non-scalar list trying to access FileInfo attributes
+            if len(self) != 1 or self._from_dir:
+                var_name = getattr(self, "_var_alias", None) or "file_list"
+                raise AttributeError(
+                    f"'{var_name}' contains {len(self)} files. "
+                    f"Use '{{{{ {var_name}[0].{attr_name} }}}}' for the first file, "
+                    f"or '{{{{ {var_name}|single.{attr_name} }}}}' if expecting exactly one file."
+                )
+
+        # Let the default AttributeError occur for truly missing attributes
+        raise AttributeError(
+            f"'{type(self).__name__}' object has no attribute '{attr_name}'"
+        )
+
     def __str__(self) -> str:
         """Get string representation of the file list.
 
         Returns:
-            str: String representation in format FileInfoList([paths])
+            str: Helpful guidance message for template usage
         """
         with self._lock:
             if not self:
                 return "FileInfoList([])"
+
+            # For single file from file mapping (--fta, -ft, etc.)
+            if len(self) == 1 and not self._from_dir:
+                var_name = self._var_alias or "file_var"
+                return f"[File '{self[0].path}' - Use {{ {var_name}.content }} to access file content]"
+
+            # For multiple files or directory mapping
+            var_name = self._var_alias or "file_list"
             if len(self) == 1:
-                return f"FileInfoList(['{self[0].path}'])"
-            return f"FileInfoList({[f.path for f in self]})"
+                return f"[Directory file '{self[0].path}' - Use {{ {var_name}[0].content }} or {{ {var_name}|single.content }} to access content]"
+            else:
+                paths_preview = [f.path for f in self[:2]]
+                if len(self) > 2:
+                    paths_preview.append(f"... +{len(self) - 2} more")
+                return f"[{len(self)} files: {', '.join(paths_preview)} - Use {{ {var_name}[0].content }} or loop over files]"
 
     def __repr__(self) -> str:
         """Get detailed string representation of the file list.