ostruct-cli 0.8.8__py3-none-any.whl → 1.0.0__py3-none-any.whl

ostruct/cli/params.py

@@ -0,0 +1,217 @@
+"""Parameter handling and validation for CLI attachment syntax."""
+
+from typing import Any, Dict, Optional, Set, Tuple, TypedDict, Union
+
+import click
+
+# Target mapping with explicit aliases
+TARGET_NORMALISE = {
+    "prompt": "prompt",
+    "code-interpreter": "code-interpreter",
+    "ci": "code-interpreter",
+    "file-search": "file-search",
+    "fs": "file-search",
+}
+
+
+class AttachmentSpec(TypedDict):
+    """Type definition for attachment specifications."""
+
+    alias: str
+    path: Union[
+        str, Tuple[str, str]
+    ]  # str or ("@", "filelist.txt") for collect
+    targets: Set[str]
+    recursive: bool
+    pattern: Optional[str]
+
+
+def normalise_targets(raw: str) -> Set[str]:
+    """Normalize comma-separated target list with aliases.
+
+    Args:
+        raw: Comma-separated string of targets (e.g., "prompt,ci,fs")
+
+    Returns:
+        Set of normalized target names
+
+    Raises:
+        click.BadParameter: If any target is unknown
+
+    Examples:
+        >>> normalise_targets("prompt")
+        {"prompt"}
+        >>> normalise_targets("ci,fs")
+        {"code-interpreter", "file-search"}
+        >>> normalise_targets("")
+        {"prompt"}
+    """
+    if not raw.strip():  # Guard against empty string edge case
+        return {"prompt"}
+
+    tokens = [t.strip().lower() for t in raw.split(",") if t.strip()]
+    if not tokens:  # After stripping, no valid tokens remain
+        return {"prompt"}
+
+    # Normalize all tokens and check for unknown ones
+    normalized = set()
+    bad_tokens = set()
+
+    for token in tokens:
+        if token in TARGET_NORMALISE:
+            normalized.add(TARGET_NORMALISE[token])
+        else:
+            bad_tokens.add(token)
+
+    if bad_tokens:
+        valid_targets = ", ".join(sorted(TARGET_NORMALISE.keys()))
+        raise click.BadParameter(
+            f"Unknown target(s): {', '.join(sorted(bad_tokens))}. "
+            f"Valid targets: {valid_targets}"
+        )
+
+    return normalized or {"prompt"}  # Fallback to prompt if somehow empty
+
+
+def validate_attachment_alias(alias: str) -> str:
+    """Validate and normalize attachment alias.
+
+    Args:
+        alias: The attachment alias to validate
+
+    Returns:
+        The validated alias
+
+    Raises:
+        click.BadParameter: If alias is invalid
+    """
+    if not alias or not alias.strip():
+        raise click.BadParameter("Attachment alias cannot be empty")
+
+    alias = alias.strip()
+
+    # Basic validation - no whitespace, reasonable length
+    if " " in alias or "\t" in alias:
+        raise click.BadParameter("Attachment alias cannot contain whitespace")
+
+    if len(alias) > 64:
+        raise click.BadParameter(
+            "Attachment alias too long (max 64 characters)"
+        )
+
+    return alias
+
+
+class AttachParam(click.ParamType):
+    """Custom Click parameter type for parsing attachment specifications.
+
+    Supports space-form syntax: '[targets:]alias path'
+
+    Examples:
+        --attach data ./file.txt
+        --attach ci:analysis ./data.csv
+        --collect ci,fs:mixed @file-list.txt
+    """
+
+    name = "attach-spec"
+
+    def __init__(self, multi: bool = False) -> None:
+        """Initialize AttachParam.
+
+        Args:
+            multi: If True, supports @filelist syntax for collect operations
+        """
+        self.multi = multi
+
+    def convert(
+        self,
+        value: Any,
+        param: Optional[click.Parameter],
+        ctx: Optional[click.Context],
+    ) -> Dict[str, Any]:
+        """Convert Click parameter value to AttachmentSpec.
+
+        Args:
+            value: Parameter value from Click (tuple for nargs=2)
+            param: Click parameter object
+            ctx: Click context
+
+        Returns:
+            Dict representing an AttachmentSpec
+
+        Raises:
+            click.BadParameter: If value format is invalid
+        """
+        # Space form only (nargs=2) - Click passes tuple
+        if not isinstance(value, tuple) or len(value) != 2:
+            self._fail_with_usage_examples(
+                "Attachment must use space form syntax", param, ctx
+            )
+
+        spec, path = value
+
+        # Parse spec part: [targets:]alias
+        if ":" in spec:
+            # Check for Windows drive letter false positive (C:\path)
+            if len(spec) == 2 and spec[1] == ":" and spec[0].isalpha():
+                # This is likely a drive letter, treat as alias only
+                prefix, alias = "prompt", spec
+            else:
+                prefix, alias = spec.split(":", 1)
+        else:
+            prefix, alias = "prompt", spec
+
+        # Normalize targets using the existing function
+        try:
+            targets = normalise_targets(prefix)
+        except click.BadParameter:
+            # Re-raise with context about attachment parsing
+            self._fail_with_usage_examples(
+                f"Invalid target(s) in '{prefix}'. Use comma-separated valid targets",
+                param,
+                ctx,
+            )
+
+        # Validate alias
+        try:
+            alias = validate_attachment_alias(alias)
+        except click.BadParameter as e:
+            self._fail_with_usage_examples(str(e), param, ctx)
+
+        # Handle collect @filelist syntax
+        if self.multi and path.startswith("@"):
+            filelist_path = path[1:]  # Remove @
+            if not filelist_path:
+                self._fail_with_usage_examples(
+                    "Filelist path cannot be empty after @", param, ctx
+                )
+            path = ("@", filelist_path)
+
+        return {
+            "alias": alias,
+            "path": path,
+            "targets": targets,
+            "recursive": False,  # Set by flag processing
+            "pattern": None,  # Set by flag processing
+        }
+
+    def _fail_with_usage_examples(
+        self,
+        message: str,
+        param: Optional[click.Parameter],
+        ctx: Optional[click.Context],
+    ) -> None:
+        """Provide helpful usage examples in error messages."""
+        examples = [
+            "--file data ./file.txt",
+            "--file ci:analysis ./data.csv",
+            "--dir fs:docs ./documentation",
+        ]
+
+        if self.multi:
+            examples.append("--collect ci,fs:mixed @file-list.txt")
+
+        full_message = f"{message}\n\nExamples:\n" + "\n".join(
+            f"  {ex}" for ex in examples
+        )
+        self.fail(full_message, param, ctx)

ostruct/cli/plan_assembly.py

@@ -0,0 +1,335 @@
+"""Plan assembly for execution plans and run summaries.
+
+This module provides the single source of truth for plan data structures
+following UNIFIED GUIDELINES to prevent logic drift between JSON and human output.
+"""
+
+import os
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .attachment_processor import ProcessedAttachments
+
+
+class PlanAssembler:
+    """Single source of truth for execution plan data structure.
+
+    This class ensures consistent plan format across all output types
+    (JSON, human-readable, etc.) by providing a single build method.
+    """
+
+    @staticmethod
+    def validate_download_configuration(
+        enabled_tools: Optional[set[str]] = None,
+        ci_config: Optional[Dict[str, Any]] = None,
+        expected_files: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """Validate download configuration for dry-run.
+
+        Args:
+            enabled_tools: Set of enabled tools
+            ci_config: Code Interpreter configuration
+            expected_files: List of expected output filenames (optional)
+
+        Returns:
+            Dictionary with validation results
+        """
+        validation: Dict[str, Any] = {
+            "enabled": False,
+            "directory": None,
+            "writable": False,
+            "conflicts": [],
+            "issues": [],
+        }
+
+        # Check if Code Interpreter is enabled
+        if not enabled_tools or "code-interpreter" not in enabled_tools:
+            return validation
+
+        validation["enabled"] = True
+
+        # Get download directory
+
+        download_dir = "./downloads"  # Default
+        if ci_config:
+            download_dir = ci_config.get("output_directory", download_dir)
+
+        validation["directory"] = download_dir
+
+        # Check directory permissions
+        try:
+            download_path = Path(download_dir)
+            parent_dir = download_path.parent
+
+            # Check if parent exists and is writable
+            if parent_dir.exists():
+                # Try to create a test file in parent
+                test_file = parent_dir / ".ostruct_write_test"
+                try:
+                    test_file.touch()
+                    test_file.unlink()
+
+                    # If download dir exists, check it specifically
+                    if download_path.exists():
+                        if not download_path.is_dir():
+                            validation["issues"].append(
+                                f"Path exists but is not a directory: {download_dir}"
+                            )
+                        else:
+                            # Test write in actual directory
+                            test_file = download_path / ".ostruct_write_test"
+                            test_file.touch()
+                            test_file.unlink()
+                            validation["writable"] = True
+                    else:
+                        # Directory doesn't exist but parent is writable
+                        validation["writable"] = True
+
+                except Exception as e:
+                    validation["issues"].append(
+                        f"Cannot write to directory: {e}"
+                    )
+            else:
+                validation["issues"].append(
+                    f"Parent directory does not exist: {parent_dir}"
+                )
+
+        except Exception as e:
+            validation["issues"].append(f"Error checking directory: {e}")
+
+        # Check for potential conflicts if expected files provided
+        if expected_files and validation["writable"]:
+            try:
+                download_path = Path(download_dir)
+                if download_path.exists():
+                    existing_files = {
+                        f.name for f in download_path.iterdir() if f.is_file()
+                    }
+                    conflicts = [
+                        f for f in expected_files if f in existing_files
+                    ]
+                    validation["conflicts"] = conflicts
+            except Exception:
+                pass  # Ignore errors in conflict detection
+
+        return validation
+
+    @staticmethod
+    def build_execution_plan(
+        processed_attachments: ProcessedAttachments,
+        template_path: str,
+        schema_path: str,
+        variables: Dict[str, Any],
+        security_mode: Optional[str] = None,
+        model: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        """Build execution plan dict with consistent schema.
+
+        Args:
+            processed_attachments: Processed attachment specifications
+            template_path: Path to template file
+            schema_path: Path to schema file
+            variables: Template variables
+            security_mode: Security mode setting
+            model: Model to use for processing
+            **kwargs: Additional context (allowed_paths, cost_estimate, template_warning, etc.)
+
+        Returns:
+            Execution plan dictionary
+        """
+        # Handle template warning information
+        template_warning = kwargs.get("template_warning")
+        original_template_path = kwargs.get("original_template_path")
+
+        # Use original path if available, otherwise use the provided path
+        display_path = original_template_path or template_path
+
+        template_info = {
+            "path": display_path,
+            "exists": (
+                Path(display_path).exists() if display_path != "---" else True
+            ),
+        }
+
+        # Add warning information if present
+        if template_warning:
+            template_info["warning"] = template_warning
+
+        schema_info = {
+            "path": schema_path,
+            "exists": Path(schema_path).exists(),
+        }
+
+        # Build plan structure
+        plan = {
+            "schema_version": "1.0",
+            "type": "execution_plan",
+            "timestamp": datetime.now().isoformat(),
+            "template": template_info,
+            "schema": schema_info,
+            "model": model or "gpt-4o",
+            "variables": variables,
+            "security_mode": security_mode or "permissive",
+            "attachments": PlanAssembler._format_attachments(
+                processed_attachments
+            ),
+        }
+
+        # Add tools section if enabled tools are provided
+        enabled_tools = kwargs.get("enabled_tools")
+        if enabled_tools:
+            tools_dict = {}
+            for tool in enabled_tools:
+                # Map tool names to boolean values for plan display
+                if tool == "code-interpreter":
+                    tools_dict["code_interpreter"] = True
+                elif tool == "file-search":
+                    tools_dict["file_search"] = True
+                elif tool == "web-search":
+                    tools_dict["web_search"] = True
+                elif tool == "mcp":
+                    tools_dict["mcp"] = True
+                elif (
+                    tool != "template"
+                ):  # Skip template as it's not an external tool
+                    tools_dict[tool] = True
+
+            if tools_dict:
+                plan["tools"] = tools_dict
+
+        # Add download validation for Code Interpreter
+        if enabled_tools and "code-interpreter" in enabled_tools:
+            # Get CI config if available
+            ci_config = kwargs.get("ci_config")
+            download_validation = (
+                PlanAssembler.validate_download_configuration(
+                    enabled_tools=enabled_tools,
+                    ci_config=ci_config,
+                    expected_files=kwargs.get("expected_files"),
+                )
+            )
+
+            # Add to plan if there are issues or useful info
+            if download_validation["enabled"]:
+                plan["download_validation"] = download_validation
+
+        # Add optional fields
+        if kwargs.get("allowed_paths"):
+            plan["allowed_paths"] = kwargs["allowed_paths"]
+        if kwargs.get("cost_estimate"):
+            plan["cost_estimate"] = kwargs["cost_estimate"]
+
+        return plan
+
+    @staticmethod
+    def build_run_summary(
+        execution_plan: Dict[str, Any],
+        result: Optional[Dict[str, Any]] = None,
+        execution_time: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        """Build run summary dict from execution plan and results.
+
+        Args:
+            execution_plan: Original execution plan
+            result: Execution results
+            execution_time: Time taken for execution
+            **kwargs: Additional summary data
+
+        Returns:
+            Dictionary with consistent run summary structure
+        """
+        summary = {
+            "schema_version": "1.0",
+            "type": "run_summary",
+            "timestamp": time.time(),
+            "execution_time": execution_time,
+            "success": kwargs.get("success", True),
+            "original_plan": execution_plan,
+        }
+
+        if result:
+            summary["result"] = result
+
+        if "error" in kwargs:
+            summary["error"] = kwargs["error"]
+            summary["success"] = False
+
+        if "cost_breakdown" in kwargs:
+            summary["cost_breakdown"] = kwargs["cost_breakdown"]
+
+        return summary
+
+    @staticmethod
+    def _format_attachments(
+        processed_attachments: ProcessedAttachments,
+    ) -> List[Dict[str, Any]]:
+        """Format processed attachments for plan output.
+
+        Args:
+            processed_attachments: Processed attachment specifications
+
+        Returns:
+            List of formatted attachment dictionaries
+        """
+        attachments = []
+
+        # Add all attachment types with consistent format
+        for alias, spec in processed_attachments.alias_map.items():
+            attachment = {
+                "alias": alias,
+                "path": spec.path,
+                "targets": sorted(
+                    list(spec.targets)
+                ),  # Ensure consistent ordering
+                "type": "file" if not spec.recursive else "directory",
+                "exists": os.path.exists(spec.path),
+                "recursive": spec.recursive,
+                "pattern": spec.pattern,
+            }
+
+            # Add metadata about where this attachment will be processed
+            tool_info = []
+            if "prompt" in spec.targets:
+                tool_info.append("template")
+            if "code-interpreter" in spec.targets or "ci" in spec.targets:
+                tool_info.append("code_interpreter")
+            if "file-search" in spec.targets or "fs" in spec.targets:
+                tool_info.append("file_search")
+
+            attachment["processing"] = tool_info
+            attachments.append(attachment)
+
+        return attachments
+
+    @staticmethod
+    def validate_plan(plan: Dict[str, Any]) -> bool:
+        """Validate plan structure for consistency.
+
+        Args:
+            plan: Plan dictionary to validate
+
+        Returns:
+            True if plan structure is valid
+
+        Raises:
+            ValueError: If plan structure is invalid
+        """
+        required_fields = ["schema_version", "type", "timestamp"]
+
+        for field in required_fields:
+            if field not in plan:
+                raise ValueError(f"Missing required field: {field}")
+
+        if plan["type"] not in ["execution_plan", "run_summary"]:
+            raise ValueError(f"Invalid plan type: {plan['type']}")
+
+        if plan["schema_version"] != "1.0":
+            raise ValueError(
+                f"Unsupported schema version: {plan['schema_version']}"
+            )
+
+        return True