tactus 0.31.2__py3-none-any.whl

tactus/sandbox/protocol.py

@@ -0,0 +1,213 @@
+"""
+Communication protocol between host and container processes.
+
+Defines the data structures for serializing execution requests and results
+over stdio between the host process and the sandboxed container.
+"""
+
+import json
+from dataclasses import dataclass, field, asdict
+from typing import Any, Dict, List, Optional
+from enum import Enum
+
+from pydantic import BaseModel
+
+
+def _json_serializer(obj: Any) -> Any:
+    """Custom JSON serializer for objects not natively serializable."""
+    if isinstance(obj, BaseModel):
+        return obj.model_dump(mode="json")
+    if hasattr(obj, "__dict__"):
+        return obj.__dict__
+    raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
+
+
+class ExecutionStatus(str, Enum):
+    """Status of sandbox execution."""
+
+    SUCCESS = "success"
+    ERROR = "error"
+    TIMEOUT = "timeout"
+    CANCELLED = "cancelled"
+
+
+@dataclass
+class ExecutionRequest:
+    """
+    Request sent from host to container for procedure execution.
+
+    Serialized as JSON over stdin to the container process.
+    """
+
+    # Procedure source code (.tac file content)
+    source: str
+
+    # Working directory path (inside container)
+    working_dir: str = "/workspace"
+
+    # Input parameters for the procedure
+    params: Dict[str, Any] = field(default_factory=dict)
+
+    # Unique execution ID for tracking
+    execution_id: Optional[str] = None
+
+    # Source file path (for error messages)
+    source_file_path: Optional[str] = None
+
+    # Source format: "lua" for .tac files, "yaml" for legacy YAML format
+    format: str = "lua"
+
+    def to_json(self) -> str:
+        """Serialize to JSON string."""
+        return json.dumps(asdict(self), indent=None, separators=(",", ":"))
+
+    @classmethod
+    def from_json(cls, json_str: str) -> "ExecutionRequest":
+        """Deserialize from JSON string."""
+        data = json.loads(json_str)
+        return cls(**data)
+
+
+@dataclass
+class ExecutionResult:
+    """
+    Result returned from container to host after execution.
+
+    Serialized as JSON over stdout from the container process.
+    """
+
+    # Execution status
+    status: ExecutionStatus
+
+    # Result value (if successful)
+    result: Optional[Any] = None
+
+    # Error message (if failed)
+    error: Optional[str] = None
+
+    # Error type/class name
+    error_type: Optional[str] = None
+
+    # Stack trace (if failed)
+    traceback: Optional[str] = None
+
+    # Execution duration in seconds
+    duration_seconds: float = 0.0
+
+    # Exit code suggestion
+    exit_code: int = 0
+
+    # Structured logs from execution
+    logs: List[Dict[str, Any]] = field(default_factory=list)
+
+    # Metadata about the execution
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def to_json(self) -> str:
+        """Serialize to JSON string."""
+        data = asdict(self)
+        # Convert enum to string for JSON
+        data["status"] = self.status.value
+        return json.dumps(data, indent=None, separators=(",", ":"), default=_json_serializer)
+
+    @classmethod
+    def from_json(cls, json_str: str) -> "ExecutionResult":
+        """Deserialize from JSON string."""
+        data = json.loads(json_str)
+        # Convert string back to enum
+        data["status"] = ExecutionStatus(data["status"])
+        return cls(**data)
+
+    @classmethod
+    def success(
+        cls,
+        result: Any,
+        duration_seconds: float = 0.0,
+        logs: Optional[List[Dict[str, Any]]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> "ExecutionResult":
+        """Create a successful result."""
+        return cls(
+            status=ExecutionStatus.SUCCESS,
+            result=result,
+            duration_seconds=duration_seconds,
+            exit_code=0,
+            logs=logs or [],
+            metadata=metadata or {},
+        )
+
+    @classmethod
+    def failure(
+        cls,
+        error: str,
+        error_type: Optional[str] = None,
+        traceback: Optional[str] = None,
+        duration_seconds: float = 0.0,
+        exit_code: int = 1,
+        logs: Optional[List[Dict[str, Any]]] = None,
+    ) -> "ExecutionResult":
+        """Create a failed result."""
+        return cls(
+            status=ExecutionStatus.ERROR,
+            error=error,
+            error_type=error_type,
+            traceback=traceback,
+            duration_seconds=duration_seconds,
+            exit_code=exit_code,
+            logs=logs or [],
+        )
+
+    @classmethod
+    def timeout(
+        cls,
+        duration_seconds: float,
+        logs: Optional[List[Dict[str, Any]]] = None,
+    ) -> "ExecutionResult":
+        """Create a timeout result."""
+        return cls(
+            status=ExecutionStatus.TIMEOUT,
+            error="Execution timed out",
+            duration_seconds=duration_seconds,
+            exit_code=124,  # Standard timeout exit code
+            logs=logs or [],
+        )
+
+
+# Protocol markers for parsing stdout
+# The result JSON is wrapped in markers to distinguish it from other output
+RESULT_START_MARKER = "<<<TACTUS_RESULT_START>>>"
+RESULT_END_MARKER = "<<<TACTUS_RESULT_END>>>"
+
+
+def wrap_result_for_stdout(result: ExecutionResult) -> str:
+    """
+    Wrap a result in markers for stdout transmission.
+
+    This allows the host to distinguish the structured result
+    from any other output (logs, debug prints, etc.)
+    """
+    return f"{RESULT_START_MARKER}\n{result.to_json()}\n{RESULT_END_MARKER}\n"
+
+
+def extract_result_from_stdout(stdout: str) -> Optional[ExecutionResult]:
+    """
+    Extract the result from stdout, looking for markers.
+
+    Returns None if no valid result is found.
+    """
+    start_idx = stdout.find(RESULT_START_MARKER)
+    if start_idx == -1:
+        return None
+
+    end_idx = stdout.find(RESULT_END_MARKER, start_idx)
+    if end_idx == -1:
+        return None
+
+    # Extract JSON between markers
+    json_start = start_idx + len(RESULT_START_MARKER)
+    json_str = stdout[json_start:end_idx].strip()
+
+    try:
+        return ExecutionResult.from_json(json_str)
+    except (json.JSONDecodeError, TypeError, KeyError):
+        return None

tactus/stdlib/__init__.py

@@ -0,0 +1,10 @@
+"""Tactus Standard Library.
+
+The standard library consists of .tac files in the tac/ subdirectory.
+These are loaded via Lua's require() function:
+
+    local done = require("tactus.tools.done")
+    local log = require("tactus.tools.log")
+
+See tactus/stdlib/tac/ for available modules.
+"""

tactus/stdlib/io/__init__.py

@@ -0,0 +1,13 @@
+"""
+tactus.stdlib.io - File I/O operations for Tactus procedures.
+
+This package provides Python-backed file I/O modules that can be
+imported via require() in .tac files.
+
+Usage:
+    local json = require("tactus.io.json")
+    local csv = require("tactus.io.csv")
+    local file = require("tactus.io.file")
+
+All file operations are sandboxed to the procedure's base directory.
+"""

tactus/stdlib/io/csv.py

@@ -0,0 +1,88 @@
+"""
+tactus.io.csv - CSV file operations for Tactus.
+
+Provides CSV read/write operations with automatic header handling
+and sandboxing to the procedure's base directory.
+
+Usage in .tac files:
+    local csv = require("tactus.io.csv")
+
+    -- Read CSV file
+    local data = csv.read("data.csv")
+
+    -- Write CSV file
+    csv.write("output.csv", {
+        {name = "Alice", age = 30},
+        {name = "Bob", age = 25}
+    })
+"""
+
+import csv
+import os
+import sys
+from typing import Any, Dict, List, Optional
+
+# Get context (injected by loader)
+_ctx = getattr(sys.modules[__name__], "__tactus_context__", None)
+
+
+def read(filepath: str) -> List[Dict[str, Any]]:
+    """
+    Read CSV file, returning list of dictionaries with headers as keys.
+
+    Args:
+        filepath: Path to CSV file (relative to working directory)
+
+    Returns:
+        List of dictionaries, one per row
+
+    Raises:
+        FileNotFoundError: If file does not exist
+        PermissionError: If path is outside working directory
+    """
+    if _ctx:
+        filepath = _ctx.validate_path(filepath)
+
+    with open(filepath, "r", encoding="utf-8", newline="") as f:
+        reader = csv.DictReader(f)
+        return list(reader)
+
+
+def write(
+    filepath: str, data: List[Dict[str, Any]], options: Optional[Dict[str, Any]] = None
+) -> None:
+    """
+    Write list of dictionaries to CSV file.
+
+    Args:
+        filepath: Path to CSV file
+        data: List of dictionaries to write
+        options: Optional dict with 'headers' key for custom header order
+
+    Raises:
+        PermissionError: If path is outside working directory
+        ValueError: If data is empty or cannot determine headers
+    """
+    if _ctx:
+        filepath = _ctx.validate_path(filepath)
+
+    if not data:
+        raise ValueError("Cannot write empty data to CSV")
+
+    # Determine headers
+    options = options or {}
+    headers = options.get("headers")
+    if not headers:
+        headers = list(data[0].keys())
+
+    # Create parent directories
+    os.makedirs(os.path.dirname(filepath) or ".", exist_ok=True)
+
+    with open(filepath, "w", encoding="utf-8", newline="") as f:
+        writer = csv.DictWriter(f, fieldnames=headers)
+        writer.writeheader()
+        writer.writerows(data)
+
+
+# Explicit exports
+__tactus_exports__ = ["read", "write"]

tactus/stdlib/io/excel.py

@@ -0,0 +1,136 @@
+"""
+tactus.io.excel - Excel spreadsheet operations for Tactus.
+
+Provides Excel read/write operations with sandboxing
+to the procedure's base directory.
+
+Requires: openpyxl
+
+Usage in .tac files:
+    local excel = require("tactus.io.excel")
+
+    -- Read Excel file
+    local data = excel.read("data.xlsx")
+
+    -- Read specific sheet
+    local data = excel.read("data.xlsx", {sheet = "Sheet2"})
+
+    -- Write Excel file
+    excel.write("output.xlsx", {
+        {name = "Alice", score = 95},
+        {name = "Bob", score = 87}
+    })
+
+    -- List sheet names
+    local sheets = excel.sheets("data.xlsx")
+"""
+
+import os
+import sys
+from typing import Any, Dict, List, Optional
+
+try:
+    from openpyxl import Workbook, load_workbook
+except ImportError:
+    raise ImportError("openpyxl is required for Excel support. Install with: pip install openpyxl")
+
+# Get context (injected by loader)
+_ctx = getattr(sys.modules[__name__], "__tactus_context__", None)
+
+
+def read(filepath: str, options: Optional[Dict[str, Any]] = None) -> List[Dict[str, Any]]:
+    """
+    Read Excel file, returning list of dictionaries.
+
+    Args:
+        filepath: Path to Excel file (relative to working directory)
+        options: Optional dict with 'sheet' key for sheet name
+
+    Returns:
+        List of dictionaries, one per row (excluding header row)
+
+    Raises:
+        FileNotFoundError: If file does not exist
+        PermissionError: If path is outside working directory
+    """
+    if _ctx:
+        filepath = _ctx.validate_path(filepath)
+
+    options = options or {}
+    sheet = options.get("sheet") if options else None
+
+    wb = load_workbook(filepath, read_only=True, data_only=True)
+    ws = wb[sheet] if sheet else wb.active
+
+    rows = list(ws.iter_rows(values_only=True))
+    if not rows:
+        return []
+
+    # First row is headers
+    headers = [str(h) if h is not None else f"col_{i}" for i, h in enumerate(rows[0])]
+    return [dict(zip(headers, row)) for row in rows[1:]]
+
+
+def write(
+    filepath: str, data: List[Dict[str, Any]], options: Optional[Dict[str, Any]] = None
+) -> None:
+    """
+    Write list of dictionaries to Excel file.
+
+    Args:
+        filepath: Path to Excel file
+        data: List of dictionaries to write
+        options: Optional dict with 'sheet' key for sheet name (default "Sheet1")
+
+    Raises:
+        PermissionError: If path is outside working directory
+        ValueError: If data is empty
+    """
+    if _ctx:
+        filepath = _ctx.validate_path(filepath)
+
+    if not data:
+        raise ValueError("Cannot write empty data to Excel")
+
+    options = options or {}
+    sheet = options.get("sheet", "Sheet1")
+
+    # Create parent directories
+    os.makedirs(os.path.dirname(filepath) or ".", exist_ok=True)
+
+    wb = Workbook()
+    ws = wb.active
+    ws.title = sheet
+
+    # Write headers and data
+    headers = list(data[0].keys())
+    ws.append(headers)
+    for row in data:
+        ws.append([row.get(h) for h in headers])
+
+    wb.save(filepath)
+
+
+def sheets(filepath: str) -> List[str]:
+    """
+    List sheet names in Excel file.
+
+    Args:
+        filepath: Path to Excel file
+
+    Returns:
+        List of sheet names
+
+    Raises:
+        FileNotFoundError: If file does not exist
+        PermissionError: If path is outside working directory
+    """
+    if _ctx:
+        filepath = _ctx.validate_path(filepath)
+
+    wb = load_workbook(filepath, read_only=True)
+    return wb.sheetnames
+
+
+# Explicit exports
+__tactus_exports__ = ["read", "write", "sheets"]

tactus/stdlib/io/file.py

@@ -0,0 +1,90 @@
+"""
+tactus.io.file - Raw text file operations for Tactus.
+
+Provides basic text file read/write operations with sandboxing
+to the procedure's base directory.
+
+Usage in .tac files:
+    local file = require("tactus.io.file")
+
+    -- Read text file
+    local content = file.read("data.txt")
+
+    -- Write text file
+    file.write("output.txt", "Hello, world!")
+
+    -- Check if file exists
+    if file.exists("config.txt") then
+        -- do something
+    end
+"""
+
+import os
+import sys
+
+# Get context (injected by loader)
+_ctx = getattr(sys.modules[__name__], "__tactus_context__", None)
+
+
+def read(filepath: str) -> str:
+    """
+    Read entire file as text.
+
+    Args:
+        filepath: Path to text file (relative to working directory)
+
+    Returns:
+        File contents as string
+
+    Raises:
+        FileNotFoundError: If file does not exist
+        PermissionError: If path is outside working directory
+    """
+    if _ctx:
+        filepath = _ctx.validate_path(filepath)
+
+    with open(filepath, "r", encoding="utf-8") as f:
+        return f.read()
+
+
+def write(filepath: str, content: str) -> None:
+    """
+    Write text to file.
+
+    Args:
+        filepath: Path to text file
+        content: Text content to write
+
+    Raises:
+        PermissionError: If path is outside working directory
+    """
+    if _ctx:
+        filepath = _ctx.validate_path(filepath)
+
+    # Create parent directories
+    os.makedirs(os.path.dirname(filepath) or ".", exist_ok=True)
+
+    with open(filepath, "w", encoding="utf-8") as f:
+        f.write(content)
+
+
+def exists(filepath: str) -> bool:
+    """
+    Check if file exists.
+
+    Args:
+        filepath: Path to file
+
+    Returns:
+        True if file exists and is accessible, False otherwise
+    """
+    try:
+        if _ctx:
+            filepath = _ctx.validate_path(filepath)
+        return os.path.exists(filepath)
+    except PermissionError:
+        return False
+
+
+# Explicit exports
+__tactus_exports__ = ["read", "write", "exists"]

tactus/stdlib/io/fs.py

@@ -0,0 +1,154 @@
+"""
+tactus.io.fs - Filesystem helpers for Tactus.
+
+Provides safe directory listing and globbing, sandboxed to the procedure's base directory.
+
+Usage in .tac files:
+    local fs = require("tactus.io.fs")
+
+    -- List files in a directory
+    local entries = fs.list_dir("chapters")
+
+    -- Glob files (sorted by default)
+    local qmd_files = fs.glob("chapters/*.qmd")
+"""
+
+from __future__ import annotations
+
+import glob as _glob
+import os
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+# Get context (injected by loader)
+_ctx = getattr(sys.modules[__name__], "__tactus_context__", None)
+
+
+def _base_path() -> str:
+    if _ctx and getattr(_ctx, "base_path", None):
+        return str(_ctx.base_path)
+    return os.getcwd()
+
+
+def _validate_relative_path(path: str) -> None:
+    # Keep semantics consistent with other stdlib IO modules:
+    # - no absolute paths
+    # - no traversal segments
+    p = Path(path)
+    if p.is_absolute():
+        raise PermissionError(f"Absolute paths not allowed: {path}")
+    if any(part == ".." for part in p.parts):
+        raise PermissionError(f"Path traversal not allowed: {path}")
+
+
+def list_dir(dirpath: str, options: Optional[Dict[str, Any]] = None) -> List[str]:
+    """
+    List entries in a directory.
+
+    Args:
+        dirpath: Directory path (relative to working directory)
+        options:
+          - files_only: bool (default True) - include only files
+          - dirs_only: bool (default False) - include only directories
+          - sort: bool (default True) - sort results
+
+    Returns:
+        List of entry paths (relative to working directory)
+    """
+    options = options or {}
+    files_only = bool(options.get("files_only", True))
+    dirs_only = bool(options.get("dirs_only", False))
+    sort = bool(options.get("sort", True))
+
+    _validate_relative_path(dirpath)
+
+    base = os.path.realpath(_base_path())
+    abs_dir = os.path.realpath(os.path.join(base, dirpath))
+
+    # Ensure the directory itself is within base path (symlink-safe via realpath)
+    if abs_dir != base and not abs_dir.startswith(base + os.sep):
+        raise PermissionError(f"Access denied: path outside working directory: {dirpath}")
+
+    if not os.path.isdir(abs_dir):
+        raise FileNotFoundError(f"Directory not found: {dirpath}")
+
+    entries: List[str] = []
+    for name in os.listdir(abs_dir):
+        abs_child = os.path.realpath(os.path.join(abs_dir, name))
+        if abs_child != base and not abs_child.startswith(base + os.sep):
+            # Skip symlink escapes
+            continue
+
+        is_dir = os.path.isdir(abs_child)
+        is_file = os.path.isfile(abs_child)
+
+        if dirs_only and not is_dir:
+            continue
+        if files_only and not is_file:
+            continue
+
+        rel = os.path.relpath(abs_child, base).replace("\\", "/")
+        entries.append(rel)
+
+    if sort:
+        entries.sort()
+
+    return entries
+
+
+def glob(pattern: str, options: Optional[Dict[str, Any]] = None) -> List[str]:
+    """
+    Glob files within the working directory.
+
+    Args:
+        pattern: Glob pattern (relative to working directory), e.g. "chapters/*.qmd"
+        options:
+          - recursive: bool (default False) - enable ** patterns
+          - files_only: bool (default True) - include only files
+          - dirs_only: bool (default False) - include only directories
+          - sort: bool (default True) - sort results
+
+    Returns:
+        List of matched paths (relative to working directory)
+    """
+    options = options or {}
+    recursive = bool(options.get("recursive", False))
+    files_only = bool(options.get("files_only", True))
+    dirs_only = bool(options.get("dirs_only", False))
+    sort = bool(options.get("sort", True))
+
+    _validate_relative_path(pattern)
+
+    base = os.path.realpath(_base_path())
+    abs_pattern = os.path.realpath(os.path.join(base, pattern))
+
+    # Ensure the pattern root is within base path (symlink-safe via realpath)
+    if abs_pattern != base and not abs_pattern.startswith(base + os.sep):
+        raise PermissionError(f"Access denied: path outside working directory: {pattern}")
+
+    matches: List[str] = []
+    for match in _glob.glob(abs_pattern, recursive=recursive):
+        abs_match = os.path.realpath(match)
+        if abs_match != base and not abs_match.startswith(base + os.sep):
+            # Skip symlink escapes
+            continue
+
+        is_dir = os.path.isdir(abs_match)
+        is_file = os.path.isfile(abs_match)
+
+        if dirs_only and not is_dir:
+            continue
+        if files_only and not is_file:
+            continue
+
+        rel = os.path.relpath(abs_match, base).replace("\\", "/")
+        matches.append(rel)
+
+    if sort:
+        matches.sort()
+
+    return matches
+
+
+__tactus_exports__ = ["list_dir", "glob"]