tasktree 0.0.6__py3-none-any.whl → 0.0.8__py3-none-any.whl

tasktree/parser.py

@@ -2,12 +2,18 @@
 
 from __future__ import annotations
 
+import os
+import platform
+import re
+import subprocess
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any
+from typing import Any, List
 
 import yaml
 
+from tasktree.types import get_click_type
+
 
 class CircularImportError(Exception):
     """Raised when a circular import is detected."""
@@ -16,12 +22,26 @@ class CircularImportError(Exception):
 
 @dataclass
 class Environment:
-    """Represents an execution environment configuration."""
+    """Represents an execution environment configuration.
+
+    Can be either a shell environment or a Docker environment:
+    - Shell environment: has 'shell' field, executes directly on host
+    - Docker environment: has 'dockerfile' field, executes in container
+    """
 
     name: str
-    shell: str
+    shell: str = ""  # Path to shell (required for shell envs, optional for Docker)
     args: list[str] = field(default_factory=list)
     preamble: str = ""
+    # Docker-specific fields (presence of dockerfile indicates Docker environment)
+    dockerfile: str = ""  # Path to Dockerfile
+    context: str = ""  # Path to build context directory
+    volumes: list[str] = field(default_factory=list)  # Volume mounts
+    ports: list[str] = field(default_factory=list)  # Port mappings
+    env_vars: dict[str, str] = field(default_factory=dict)  # Environment variables
+    working_dir: str = ""  # Working directory (container or host)
+    extra_args: List[str] = field(default_factory=list) # Any extra arguments to pass to docker
+    run_as_root: bool = False  # If True, skip user mapping (run as root in container)
 
     def __post_init__(self):
         """Ensure args is always a list."""
@@ -56,15 +76,39 @@ class Task:
             self.args = [self.args]
 
 
+@dataclass
+class ArgSpec:
+    """Represents a parsed argument specification.
+
+    Attributes:
+        name: Argument name
+        arg_type: Type of the argument (str, int, float, bool, path)
+        default: Default value as a string (None if no default)
+        is_exported: Whether the argument is exported as an environment variable
+        min_val: Minimum value for numeric arguments (None if not specified)
+        max_val: Maximum value for numeric arguments (None if not specified)
+        choices: List of valid choices for the argument (None if not specified)
+    """
+    name: str
+    arg_type: str
+    default: str | None = None
+    is_exported: bool = False
+    min_val: int | float | None = None
+    max_val: int | float | None = None
+    choices: list[Any] | None = None
+
+
 @dataclass
 class Recipe:
     """Represents a parsed recipe file with all tasks."""
 
     tasks: dict[str, Task]
     project_root: Path
+    recipe_path: Path  # Path to the recipe file
     environments: dict[str, Environment] = field(default_factory=dict)
     default_env: str = ""  # Name of default environment
     global_env_override: str = ""  # Global environment override (set via CLI --env)
+    variables: dict[str, str] = field(default_factory=dict)  # Global variables (resolved at parse time)
 
     def get_task(self, name: str) -> Task | None:
         """Get task by name.
@@ -156,13 +200,603 @@ def find_recipe_file(start_dir: Path | None = None) -> Path | None:
     return None
 
 
+def _validate_variable_name(name: str) -> None:
+    """Validate that a variable name is a valid identifier.
+
+    Args:
+        name: Variable name to validate
+
+    Raises:
+        ValueError: If name is not a valid identifier
+    """
+    if not re.match(r'^[a-zA-Z_][a-zA-Z0-9_]*$', name):
+        raise ValueError(
+            f"Variable name '{name}' is invalid. Names must start with "
+            f"letter/underscore and contain only alphanumerics and underscores."
+        )
+
+
+def _infer_variable_type(value: Any) -> str:
+    """Infer type name from Python value.
+
+    Args:
+        value: Python value from YAML
+
+    Returns:
+        Type name string (str, int, float, bool)
+
+    Raises:
+        ValueError: If value type is not supported
+    """
+    type_map = {
+        str: "str",
+        int: "int",
+        float: "float",
+        bool: "bool"
+    }
+    python_type = type(value)
+    if python_type not in type_map:
+        raise ValueError(
+            f"Variable has unsupported type '{python_type.__name__}'. "
+            f"Supported types: str, int, float, bool, path, datetime, ip, ipv4, ipv6, email, hostname"
+        )
+    return type_map[python_type]
+
+
+def _is_env_variable_reference(value: Any) -> bool:
+    """Check if value is an environment variable reference.
+
+    Args:
+        value: Raw value from YAML
+
+    Returns:
+        True if value is { env: VAR_NAME } dict
+    """
+    return isinstance(value, dict) and "env" in value
+
+
+def _validate_env_variable_reference(var_name: str, value: dict) -> str:
+    """Validate and extract environment variable name from reference.
+
+    Args:
+        var_name: Name of the variable being defined
+        value: Dict that should be { env: ENV_VAR_NAME }
+
+    Returns:
+        Environment variable name
+
+    Raises:
+        ValueError: If reference is invalid
+    """
+    # Validate dict structure
+    if len(value) != 1:
+        extra_keys = [k for k in value.keys() if k != "env"]
+        raise ValueError(
+            f"Invalid environment variable reference in variable '{var_name}'.\n"
+            f"Expected: {{ env: VARIABLE_NAME }}\n"
+            f"Found extra keys: {', '.join(extra_keys)}"
+        )
+
+    env_var_name = value["env"]
+
+    # Validate env var name is provided
+    if not env_var_name or not isinstance(env_var_name, str):
+        raise ValueError(
+            f"Invalid environment variable reference in variable '{var_name}'.\n"
+            f"Expected: {{ env: VARIABLE_NAME }}\n"
+            f"Found: {{ env: {env_var_name!r} }}"
+        )
+
+    # Validate env var name format (allow both uppercase and mixed case for flexibility)
+    if not re.match(r'^[a-zA-Z_][a-zA-Z0-9_]*$', env_var_name):
+        raise ValueError(
+            f"Invalid environment variable name '{env_var_name}' in variable '{var_name}'.\n"
+            f"Environment variable names must start with a letter or underscore,\n"
+            f"and contain only alphanumerics and underscores."
+        )
+
+    return env_var_name
+
+
+def _resolve_env_variable(var_name: str, env_var_name: str) -> str:
+    """Resolve environment variable value.
+
+    Args:
+        var_name: Name of the variable being defined
+        env_var_name: Name of environment variable to read
+
+    Returns:
+        Environment variable value as string
+
+    Raises:
+        ValueError: If environment variable is not set
+    """
+    value = os.environ.get(env_var_name)
+
+    if value is None:
+        raise ValueError(
+            f"Environment variable '{env_var_name}' (referenced by variable '{var_name}') is not set.\n\n"
+            f"Hint: Set it before running tt:\n"
+            f"  {env_var_name}=value tt task\n\n"
+            f"Or export it in your shell:\n"
+            f"  export {env_var_name}=value\n"
+            f"  tt task"
+        )
+
+    return value
+
+
+def _is_file_read_reference(value: Any) -> bool:
+    """Check if value is a file read reference.
+
+    Args:
+        value: Raw value from YAML
+
+    Returns:
+        True if value is { read: filepath } dict
+    """
+    return isinstance(value, dict) and "read" in value
+
+
+def _validate_file_read_reference(var_name: str, value: dict) -> str:
+    """Validate and extract filepath from file read reference.
+
+    Args:
+        var_name: Name of the variable being defined
+        value: Dict that should be { read: filepath }
+
+    Returns:
+        Filepath string
+
+    Raises:
+        ValueError: If reference is invalid
+    """
+    # Validate dict structure (only "read" key allowed)
+    if len(value) != 1:
+        extra_keys = [k for k in value.keys() if k != "read"]
+        raise ValueError(
+            f"Invalid file read reference in variable '{var_name}'.\n"
+            f"Expected: {{ read: filepath }}\n"
+            f"Found extra keys: {', '.join(extra_keys)}"
+        )
+
+    filepath = value["read"]
+
+    # Validate filepath is provided and is a string
+    if not filepath or not isinstance(filepath, str):
+        raise ValueError(
+            f"Invalid file read reference in variable '{var_name}'.\n"
+            f"Expected: {{ read: filepath }}\n"
+            f"Found: {{ read: {filepath!r} }}\n\n"
+            f"Filepath must be a non-empty string."
+        )
+
+    return filepath
+
+
+def _resolve_file_path(filepath: str, recipe_file_path: Path) -> Path:
+    """Resolve file path relative to recipe file location.
+
+    Handles three path types:
+    1. Tilde paths (~): Expand to user home directory
+    2. Absolute paths: Use as-is
+    3. Relative paths: Resolve relative to recipe file's directory
+
+    Args:
+        filepath: Path string from YAML (may be relative, absolute, or tilde)
+        recipe_file_path: Path to the recipe file containing the variable
+
+    Returns:
+        Resolved absolute Path object
+    """
+    # Expand tilde to home directory
+    if filepath.startswith("~"):
+        return Path(os.path.expanduser(filepath))
+
+    # Convert to Path for is_absolute check
+    path_obj = Path(filepath)
+
+    # Absolute paths used as-is
+    if path_obj.is_absolute():
+        return path_obj
+
+    # Relative paths resolved from recipe file's directory
+    return recipe_file_path.parent / filepath
+
+
+def _resolve_file_variable(var_name: str, filepath: str, resolved_path: Path) -> str:
+    """Read file contents for variable value.
+
+    Args:
+        var_name: Name of the variable being defined
+        filepath: Original filepath string (for error messages)
+        resolved_path: Resolved absolute path to the file
+
+    Returns:
+        File contents as string (with trailing newline stripped)
+
+    Raises:
+        ValueError: If file doesn't exist, can't be read, or contains invalid UTF-8
+    """
+    # Check file exists
+    if not resolved_path.exists():
+        raise ValueError(
+            f"Failed to read file for variable '{var_name}': {filepath}\n"
+            f"File not found: {resolved_path}\n\n"
+            f"Note: Relative paths are resolved from the recipe file location."
+        )
+
+    # Check it's a file (not directory)
+    if not resolved_path.is_file():
+        raise ValueError(
+            f"Failed to read file for variable '{var_name}': {filepath}\n"
+            f"Path is not a file: {resolved_path}"
+        )
+
+    # Read file with UTF-8 error handling
+    try:
+        content = resolved_path.read_text(encoding='utf-8')
+    except PermissionError:
+        raise ValueError(
+            f"Failed to read file for variable '{var_name}': {filepath}\n"
+            f"Permission denied: {resolved_path}\n\n"
+            f"Ensure the file is readable by the current user."
+        )
+    except UnicodeDecodeError as e:
+        raise ValueError(
+            f"Failed to read file for variable '{var_name}': {filepath}\n"
+            f"File contains invalid UTF-8 data: {resolved_path}\n\n"
+            f"The {{ read: ... }} syntax only supports text files.\n"
+            f"Error: {e}"
+        )
+
+    # Strip single trailing newline if present
+    if content.endswith('\n'):
+        content = content[:-1]
+
+    return content
+
+
+def _is_eval_reference(value: Any) -> bool:
+    """Check if value is an eval command reference.
+
+    Args:
+        value: Raw value from YAML
+
+    Returns:
+        True if value is { eval: command } dict
+    """
+    return isinstance(value, dict) and "eval" in value
+
+
+def _validate_eval_reference(var_name: str, value: dict) -> str:
+    """Validate and extract command from eval reference.
+
+    Args:
+        var_name: Name of the variable being defined
+        value: Dict that should be { eval: command }
+
+    Returns:
+        Command string
+
+    Raises:
+        ValueError: If reference is invalid
+    """
+    # Validate dict structure (only "eval" key allowed)
+    if len(value) != 1:
+        extra_keys = [k for k in value.keys() if k != "eval"]
+        raise ValueError(
+            f"Invalid eval reference in variable '{var_name}'.\n"
+            f"Expected: {{ eval: command }}\n"
+            f"Found extra keys: {', '.join(extra_keys)}"
+        )
+
+    command = value["eval"]
+
+    # Validate command is provided and is a string
+    if not command or not isinstance(command, str):
+        raise ValueError(
+            f"Invalid eval reference in variable '{var_name}'.\n"
+            f"Expected: {{ eval: command }}\n"
+            f"Found: {{ eval: {command!r} }}\n\n"
+            f"Command must be a non-empty string."
+        )
+
+    return command
+
+
+def _get_default_shell_and_args() -> tuple[str, list[str]]:
+    """Get default shell and args for current platform.
+
+    Returns:
+        Tuple of (shell, args) for platform default
+    """
+    is_windows = platform.system() == "Windows"
+    if is_windows:
+        return ("cmd", ["/c"])
+    else:
+        return ("bash", ["-c"])
+
+
+def _resolve_eval_variable(
+    var_name: str,
+    command: str,
+    recipe_file_path: Path,
+    recipe_data: dict
+) -> str:
+    """Execute command and capture output for variable value.
+
+    Args:
+        var_name: Name of the variable being defined
+        command: Command to execute
+        recipe_file_path: Path to recipe file (for working directory)
+        recipe_data: Parsed YAML data (for accessing default_env)
+
+    Returns:
+        Command stdout as string (with trailing newline stripped)
+
+    Raises:
+        ValueError: If command fails or cannot be executed
+    """
+    # Determine shell to use
+    shell = None
+    shell_args = []
+
+    # Check if recipe has default_env specified
+    if recipe_data and "environments" in recipe_data:
+        env_data = recipe_data["environments"]
+        if isinstance(env_data, dict):
+            default_env_name = env_data.get("default", "")
+            if default_env_name and default_env_name in env_data:
+                env_config = env_data[default_env_name]
+                if isinstance(env_config, dict):
+                    shell = env_config.get("shell", "")
+                    shell_args = env_config.get("args", [])
+                    if isinstance(shell_args, str):
+                        shell_args = [shell_args]
+
+    # Use platform default if no environment specified or not found
+    if not shell:
+        shell, shell_args = _get_default_shell_and_args()
+
+    # Build command list
+    cmd_list = [shell] + shell_args + [command]
+
+    # Execute from recipe file directory
+    working_dir = recipe_file_path.parent
+
+    try:
+        result = subprocess.run(
+            cmd_list,
+            capture_output=True,
+            text=True,
+            cwd=working_dir,
+            check=False,
+        )
+    except FileNotFoundError:
+        raise ValueError(
+            f"Failed to execute command for variable '{var_name}'.\n"
+            f"Shell not found: {shell}\n\n"
+            f"Command: {command}\n\n"
+            f"Ensure the shell is installed and available in PATH."
+        )
+    except Exception as e:
+        raise ValueError(
+            f"Failed to execute command for variable '{var_name}'.\n"
+            f"Command: {command}\n"
+            f"Error: {e}"
+        )
+
+    # Check exit code
+    if result.returncode != 0:
+        stderr_output = result.stderr.strip() if result.stderr else "(no stderr output)"
+        raise ValueError(
+            f"Command failed for variable '{var_name}': {command}\n"
+            f"Exit code: {result.returncode}\n"
+            f"stderr: {stderr_output}\n\n"
+            f"Ensure the command succeeds when run from the recipe file location."
+        )
+
+    # Get stdout and strip trailing newline
+    output = result.stdout
+
+    # Strip single trailing newline if present
+    if output.endswith('\n'):
+        output = output[:-1]
+
+    return output
+
+
+def _resolve_variable_value(
+    name: str,
+    raw_value: Any,
+    resolved: dict[str, str],
+    resolution_stack: list[str],
+    file_path: Path,
+    recipe_data: dict | None = None
+) -> str:
+    """Resolve a single variable value with circular reference detection.
+
+    Args:
+        name: Variable name being resolved
+        raw_value: Raw value from YAML (int, str, bool, float, dict with env/read/eval)
+        resolved: Dictionary of already-resolved variables
+        resolution_stack: Stack of variables currently being resolved (for circular detection)
+        file_path: Path to recipe file (for resolving relative file paths in { read: ... })
+        recipe_data: Parsed YAML data (for accessing default_env in { eval: ... })
+
+    Returns:
+        Resolved string value
+
+    Raises:
+        ValueError: If circular reference detected or validation fails
+    """
+    # Check for circular reference
+    if name in resolution_stack:
+        cycle = " -> ".join(resolution_stack + [name])
+        raise ValueError(f"Circular reference detected in variables: {cycle}")
+
+    resolution_stack.append(name)
+
+    try:
+        # Check if this is an eval reference
+        if _is_eval_reference(raw_value):
+            # Validate and extract command
+            command = _validate_eval_reference(name, raw_value)
+
+            # Execute command and capture output
+            string_value = _resolve_eval_variable(name, command, file_path, recipe_data)
+
+            # Still perform variable-in-variable substitution
+            from tasktree.substitution import substitute_variables
+            try:
+                resolved_value = substitute_variables(string_value, resolved)
+            except ValueError as e:
+                # Check if the undefined variable is in the resolution stack (circular reference)
+                error_msg = str(e)
+                if "not defined" in error_msg:
+                    match = re.search(r"Variable '(\w+)' is not defined", error_msg)
+                    if match:
+                        undefined_var = match.group(1)
+                        if undefined_var in resolution_stack:
+                            cycle = " -> ".join(resolution_stack + [undefined_var])
+                            raise ValueError(f"Circular reference detected in variables: {cycle}")
+                # Re-raise the original error if not circular
+                raise
+
+            return resolved_value
+
+        # Check if this is a file read reference
+        if _is_file_read_reference(raw_value):
+            # Validate and extract filepath
+            filepath = _validate_file_read_reference(name, raw_value)
+
+            # Resolve path (handles tilde, absolute, relative)
+            resolved_path = _resolve_file_path(filepath, file_path)
+
+            # Read file contents
+            string_value = _resolve_file_variable(name, filepath, resolved_path)
+
+            # Still perform variable-in-variable substitution
+            from tasktree.substitution import substitute_variables
+            try:
+                resolved_value = substitute_variables(string_value, resolved)
+            except ValueError as e:
+                # Check if the undefined variable is in the resolution stack (circular reference)
+                error_msg = str(e)
+                if "not defined" in error_msg:
+                    match = re.search(r"Variable '(\w+)' is not defined", error_msg)
+                    if match:
+                        undefined_var = match.group(1)
+                        if undefined_var in resolution_stack:
+                            cycle = " -> ".join(resolution_stack + [undefined_var])
+                            raise ValueError(f"Circular reference detected in variables: {cycle}")
+                # Re-raise the original error if not circular
+                raise
+
+            return resolved_value
+
+        # Check if this is an environment variable reference
+        if _is_env_variable_reference(raw_value):
+            # Validate and extract env var name
+            env_var_name = _validate_env_variable_reference(name, raw_value)
+
+            # Resolve from os.environ
+            string_value = _resolve_env_variable(name, env_var_name)
+
+            # Still perform variable-in-variable substitution
+            from tasktree.substitution import substitute_variables
+            try:
+                resolved_value = substitute_variables(string_value, resolved)
+            except ValueError as e:
+                # Check if the undefined variable is in the resolution stack (circular reference)
+                error_msg = str(e)
+                if "not defined" in error_msg:
+                    match = re.search(r"Variable '(\w+)' is not defined", error_msg)
+                    if match:
+                        undefined_var = match.group(1)
+                        if undefined_var in resolution_stack:
+                            cycle = " -> ".join(resolution_stack + [undefined_var])
+                            raise ValueError(f"Circular reference detected in variables: {cycle}")
+                # Re-raise the original error if not circular
+                raise
+
+            return resolved_value
+
+        # Validate and infer type
+        type_name = _infer_variable_type(raw_value)
+        from tasktree.types import get_click_type
+        validator = get_click_type(type_name)
+
+        # Validate and stringify the value
+        string_value = validator.convert(raw_value, None, None)
+
+        # Substitute any {{ var.name }} references in the string value
+        from tasktree.substitution import substitute_variables
+        try:
+            resolved_value = substitute_variables(str(string_value), resolved)
+        except ValueError as e:
+            # Check if the undefined variable is in the resolution stack (circular reference)
+            error_msg = str(e)
+            if "not defined" in error_msg:
+                # Extract the variable name from the error message
+                import re
+                match = re.search(r"Variable '(\w+)' is not defined", error_msg)
+                if match:
+                    undefined_var = match.group(1)
+                    if undefined_var in resolution_stack:
+                        cycle = " -> ".join(resolution_stack + [undefined_var])
+                        raise ValueError(f"Circular reference detected in variables: {cycle}")
+            # Re-raise the original error if not circular
+            raise
+
+        return resolved_value
+    finally:
+        resolution_stack.pop()
+
+
+def _parse_variables_section(data: dict, file_path: Path) -> dict[str, str]:
+    """Parse and resolve the variables section from YAML data.
+
+    Variables are resolved in order, allowing variables to reference
+    previously-defined variables using {{ var.name }} syntax.
+
+    Args:
+        data: Parsed YAML data (root level)
+        file_path: Path to the recipe file (for resolving relative file paths)
+
+    Returns:
+        Dictionary mapping variable names to resolved string values
+
+    Raises:
+        ValueError: For validation errors, undefined refs, or circular refs
+    """
+    if "variables" not in data:
+        return {}
+
+    vars_data = data["variables"]
+    if not isinstance(vars_data, dict):
+        raise ValueError("'variables' must be a dictionary")
+
+    resolved = {}  # name -> resolved string value
+    resolution_stack = []  # For circular detection
+
+    for var_name, raw_value in vars_data.items():
+        _validate_variable_name(var_name)
+        resolved[var_name] = _resolve_variable_value(
+            var_name, raw_value, resolved, resolution_stack, file_path, data
+        )
+
+    return resolved
+
+
 def _parse_file_with_env(
     file_path: Path,
     namespace: str | None,
     project_root: Path,
     import_stack: list[Path] | None = None,
-) -> tuple[dict[str, Task], dict[str, Environment], str]:
-    """Parse file and extract tasks and environments.
+) -> tuple[dict[str, Task], dict[str, Environment], str, dict[str, str]]:
+    """Parse file and extract tasks, environments, and variables.
 
     Args:
         file_path: Path to YAML file
@@ -171,20 +805,38 @@ def _parse_file_with_env(
         import_stack: Stack of files being imported (for circular detection)
 
     Returns:
-        Tuple of (tasks, environments, default_env_name)
+        Tuple of (tasks, environments, default_env_name, variables)
     """
     # Parse tasks normally
     tasks = _parse_file(file_path, namespace, project_root, import_stack)
 
-    # Load YAML again to extract environments (only from root file)
+    # Load YAML again to extract environments and variables (only from root file)
     environments: dict[str, Environment] = {}
     default_env = ""
+    variables: dict[str, str] = {}
 
-    # Only parse environments from the root file (namespace is None)
+    # Only parse environments and variables from the root file (namespace is None)
     if namespace is None:
         with open(file_path, "r") as f:
             data = yaml.safe_load(f)
 
+        # Parse variables first (so they can be used in environment preambles and tasks)
+        if data:
+            variables = _parse_variables_section(data, file_path)
+
+        # Apply variable substitution to all tasks
+        if variables:
+            from tasktree.substitution import substitute_variables
+
+            for task in tasks.values():
+                task.cmd = substitute_variables(task.cmd, variables)
+                task.desc = substitute_variables(task.desc, variables)
+                task.working_dir = substitute_variables(task.working_dir, variables)
+                task.inputs = [substitute_variables(inp, variables) for inp in task.inputs]
+                task.outputs = [substitute_variables(out, variables) for out in task.outputs]
+                # Substitute in argument default values (in arg spec strings)
+                task.args = [substitute_variables(arg, variables) for arg in task.args]
+
         if data and "environments" in data:
             env_data = data["environments"]
             if isinstance(env_data, dict):
@@ -201,21 +853,83 @@ def _parse_file_with_env(
                             f"Environment '{env_name}' must be a dictionary"
                         )
 
-                    # Parse environment configuration
+                    # Parse common environment configuration
                     shell = env_config.get("shell", "")
-                    if not shell:
+                    args = env_config.get("args", [])
+                    preamble = env_config.get("preamble", "")
+                    working_dir = env_config.get("working_dir", "")
+
+                    # Substitute variables in preamble
+                    if preamble and variables:
+                        from tasktree.substitution import substitute_variables
+                        preamble = substitute_variables(preamble, variables)
+
+                    # Parse Docker-specific fields
+                    dockerfile = env_config.get("dockerfile", "")
+                    context = env_config.get("context", "")
+                    volumes = env_config.get("volumes", [])
+                    ports = env_config.get("ports", [])
+                    env_vars = env_config.get("env_vars", {})
+                    extra_args = env_config.get("extra_args", [])
+                    run_as_root = env_config.get("run_as_root", False)
+
+                    # Validate environment type
+                    if not shell and not dockerfile:
                         raise ValueError(
-                            f"Environment '{env_name}' must specify 'shell'"
+                            f"Environment '{env_name}' must specify either 'shell' "
+                            f"(for shell environments) or 'dockerfile' (for Docker environments)"
                         )
 
-                    args = env_config.get("args", [])
-                    preamble = env_config.get("preamble", "")
+                    # Validate Docker environment requirements
+                    if dockerfile and not context:
+                        raise ValueError(
+                            f"Docker environment '{env_name}' must specify 'context' "
+                            f"when 'dockerfile' is specified"
+                        )
+
+                    # Validate that Dockerfile exists if specified
+                    if dockerfile:
+                        dockerfile_path = project_root / dockerfile
+                        if not dockerfile_path.exists():
+                            raise ValueError(
+                                f"Environment '{env_name}': Dockerfile not found at {dockerfile_path}"
+                            )
+
+                    # Validate that context directory exists if specified
+                    if context:
+                        context_path = project_root / context
+                        if not context_path.exists():
+                            raise ValueError(
+                                f"Environment '{env_name}': context directory not found at {context_path}"
+                            )
+                        if not context_path.is_dir():
+                            raise ValueError(
+                                f"Environment '{env_name}': context must be a directory, got {context_path}"
+                            )
+
+                    # Validate environment name (must be valid Docker tag)
+                    if not env_name.replace("-", "").replace("_", "").isalnum():
+                        raise ValueError(
+                            f"Environment name '{env_name}' must be alphanumeric "
+                            f"(with optional hyphens and underscores)"
+                        )
 
                     environments[env_name] = Environment(
-                        name=env_name, shell=shell, args=args, preamble=preamble
+                        name=env_name,
+                        shell=shell,
+                        args=args,
+                        preamble=preamble,
+                        dockerfile=dockerfile,
+                        context=context,
+                        volumes=volumes,
+                        ports=ports,
+                        env_vars=env_vars,
+                        working_dir=working_dir,
+                        extra_args=extra_args,
+                        run_as_root=run_as_root
                     )
 
-    return tasks, environments, default_env
+    return tasks, environments, default_env, variables
 
 
 def parse_recipe(recipe_path: Path, project_root: Path | None = None) -> Recipe:
@@ -243,15 +957,17 @@ def parse_recipe(recipe_path: Path, project_root: Path | None = None) -> Recipe:
         project_root = recipe_path.parent
 
     # Parse main file - it will recursively handle all imports
-    tasks, environments, default_env = _parse_file_with_env(
+    tasks, environments, default_env, variables = _parse_file_with_env(
         recipe_path, namespace=None, project_root=project_root
     )
 
     return Recipe(
         tasks=tasks,
         project_root=project_root,
+        recipe_path=recipe_path,
         environments=environments,
         default_env=default_env,
+        variables=variables,
     )
 
 
@@ -334,8 +1050,8 @@ def _parse_file(
 
             tasks.update(nested_tasks)
 
-    # Validate top-level keys (only imports, environments, and tasks are allowed)
-    VALID_TOP_LEVEL_KEYS = {"imports", "environments", "tasks"}
+    # Validate top-level keys (only imports, environments, tasks, and variables are allowed)
+    VALID_TOP_LEVEL_KEYS = {"imports", "environments", "tasks", "variables"}
 
     # Check if tasks key is missing when there appear to be task definitions at root
     # Do this BEFORE checking for unknown keys, to provide better error message
@@ -425,8 +1141,13 @@ def _parse_file(
             working_dir=working_dir,
             args=task_data.get("args", []),
             source_file=str(file_path),
+            env=task_data.get("env", ""),
         )
 
+        # Check for case-sensitive argument collisions
+        if task.args:
+            _check_case_sensitive_arg_collisions(task.args, full_name)
+
         tasks[full_name] = task
 
     # Remove current file from stack
@@ -435,28 +1156,118 @@ def _parse_file(
     return tasks
 
 
-def parse_arg_spec(arg_spec: str) -> tuple[str, str, str | None]:
-    """Parse argument specification.
+def _check_case_sensitive_arg_collisions(args: list[str], task_name: str) -> None:
+    """Check for exported arguments that differ only in case.
+
+    On Unix systems, environment variables are case-sensitive, but having
+    args that differ only in case (e.g., $Server and $server) can be confusing.
+    This function emits a warning if such collisions are detected.
 
-    Format: name:type=default
-    - name is required
-    - type is optional (defaults to 'str')
-    - default is optional
+    Args:
+        args: List of argument specifications
+        task_name: Name of the task (for warning message)
+    """
+    import sys
+
+    # Parse all exported arg names
+    exported_names = []
+    for arg_spec in args:
+        parsed = parse_arg_spec(arg_spec)
+        if parsed.is_exported:
+            exported_names.append(parsed.name)
+
+    # Check for case collisions
+    seen_lower = {}
+    for name in exported_names:
+        lower_name = name.lower()
+        if lower_name in seen_lower:
+            # Found a collision
+            other_name = seen_lower[lower_name]
+            if name != other_name:  # Only warn if actual case differs
+                print(
+                    f"Warning: Task '{task_name}' has exported arguments that differ only in case: "
+                    f"${other_name} and ${name}. "
+                    f"This may be confusing on case-sensitive systems.",
+                    file=sys.stderr
+                )
+        else:
+            seen_lower[lower_name] = name
+
+
+def parse_arg_spec(arg_spec: str | dict) -> ArgSpec:
+    """Parse argument specification from YAML.
+
+    Supports both string format and dictionary format:
+
+    String format:
+        - Simple name: "argname"
+        - Exported (becomes env var): "$argname"
+        - With default: "argname=value" or "$argname=value"
+        - Legacy type syntax: "argname:type=value" (for backwards compat)
+
+    Dictionary format:
+        - argname: { default: "value" }
+        - argname: { type: int, default: 42 }
+        - argname: { type: int, min: 1, max: 100 }
+        - argname: { type: str, choices: ["dev", "staging", "prod"] }
+        - $argname: { default: "value" }  # Exported
 
     Args:
-        arg_spec: Argument specification string
+        arg_spec: Argument specification (string or dict with single key)
 
     Returns:
-        Tuple of (name, type, default)
+        ArgSpec object containing parsed argument information
 
     Examples:
         >>> parse_arg_spec("environment")
-        ('environment', 'str', None)
-        >>> parse_arg_spec("region=eu-west-1")
-        ('region', 'str', 'eu-west-1')
-        >>> parse_arg_spec("port:int=8080")
-        ('port', 'int', '8080')
+        ArgSpec(name='environment', arg_type='str', default=None, is_exported=False, min_val=None, max_val=None, choices=None)
+        >>> parse_arg_spec({"key2": {"default": "foo"}})
+        ArgSpec(name='key2', arg_type='str', default='foo', is_exported=False, min_val=None, max_val=None, choices=None)
+        >>> parse_arg_spec({"key3": {"type": "int", "default": 42}})
+        ArgSpec(name='key3', arg_type='int', default='42', is_exported=False, min_val=None, max_val=None, choices=None)
+        >>> parse_arg_spec({"replicas": {"type": "int", "min": 1, "max": 100}})
+        ArgSpec(name='replicas', arg_type='int', default=None, is_exported=False, min_val=1, max_val=100, choices=None)
+        >>> parse_arg_spec({"env": {"type": "str", "choices": ["dev", "prod"]}})
+        ArgSpec(name='env', arg_type='str', default=None, is_exported=False, min_val=None, max_val=None, choices=['dev', 'prod'])
+
+    Raises:
+        ValueError: If argument specification is invalid
     """
+    # Handle dictionary format: { argname: { type: ..., default: ... } }
+    if isinstance(arg_spec, dict):
+        if len(arg_spec) != 1:
+            raise ValueError(
+                f"Argument dictionary must have exactly one key (the argument name), got: {list(arg_spec.keys())}"
+            )
+
+        # Extract the argument name and its configuration
+        arg_name, config = next(iter(arg_spec.items()))
+
+        # Check if argument is exported (name starts with $)
+        is_exported = arg_name.startswith("$")
+        if is_exported:
+            arg_name = arg_name[1:]  # Remove $ prefix
+
+        # Validate argument name
+        if not arg_name or not isinstance(arg_name, str):
+            raise ValueError(
+                f"Argument name must be a non-empty string, got: {arg_name!r}"
+            )
+
+        # Config must be a dictionary
+        if not isinstance(config, dict):
+            raise ValueError(
+                f"Argument '{arg_name}' configuration must be a dictionary, got: {type(config).__name__}"
+            )
+
+        return _parse_arg_dict(arg_name, config, is_exported)
+
+    # Handle string format
+    # Check if argument is exported (starts with $)
+    is_exported = arg_spec.startswith("$")
+    if is_exported:
+        arg_spec = arg_spec[1:]  # Remove $ prefix
+
     # Split on = to separate name:type from default
     if "=" in arg_spec:
         name_type, default = arg_spec.split("=", 1)
@@ -467,8 +1278,264 @@ def parse_arg_spec(arg_spec: str) -> tuple[str, str, str | None]:
     # Split on : to separate name from type
     if ":" in name_type:
         name, arg_type = name_type.split(":", 1)
+
+        # Exported arguments cannot have type annotations
+        if is_exported:
+            raise ValueError(
+                f"Type annotations not allowed on exported arguments\n"
+                f"In argument: ${name}:{arg_type}\n\n"
+                f"Exported arguments are always strings. Remove the type annotation:\n"
+                f"  args: [${name}]"
+            )
     else:
         name = name_type
         arg_type = "str"
 
-    return name, arg_type, default
+    # String format doesn't support min/max/choices
+    return ArgSpec(
+        name=name,
+        arg_type=arg_type,
+        default=default,
+        is_exported=is_exported,
+        min_val=None,
+        max_val=None,
+        choices=None
+    )
+
+
+def _parse_arg_dict(arg_name: str, config: dict, is_exported: bool) -> ArgSpec:
+    """Parse argument specification from dictionary format.
+
+    Args:
+        arg_name: Name of the argument
+        config: Dictionary with optional keys: type, default, min, max, choices
+        is_exported: Whether argument should be exported to environment
+
+    Returns:
+        ArgSpec object containing the parsed argument specification
+
+    Raises:
+        ValueError: If dictionary format is invalid
+    """
+    # Validate dictionary keys
+    valid_keys = {"type", "default", "min", "max", "choices"}
+    invalid_keys = set(config.keys()) - valid_keys
+    if invalid_keys:
+        raise ValueError(
+            f"Invalid keys in argument '{arg_name}' configuration: {', '.join(sorted(invalid_keys))}\n"
+            f"Valid keys are: {', '.join(sorted(valid_keys))}"
+        )
+
+    # Extract values
+    arg_type = config.get("type")
+    default = config.get("default")
+    min_val = config.get("min")
+    max_val = config.get("max")
+    choices = config.get("choices")
+
+    # Track if an explicit type was provided (for validation later)
+    explicit_type = arg_type
+
+    # Exported arguments cannot have type annotations
+    if is_exported and arg_type is not None:
+        raise ValueError(
+            f"Type annotations not allowed on exported argument '${arg_name}'\n"
+            f"Exported arguments are always strings. Remove the 'type' field"
+        )
+
+    # Validate choices
+    if choices is not None:
+        # Validate choices is a list
+        if not isinstance(choices, list):
+            raise ValueError(
+                f"Argument '{arg_name}': choices must be a list"
+            )
+
+        # Validate choices is not empty
+        if len(choices) == 0:
+            raise ValueError(
+                f"Argument '{arg_name}': choices list cannot be empty"
+            )
+
+        # Check for mutual exclusivity with min/max
+        if min_val is not None or max_val is not None:
+            raise ValueError(
+                f"Argument '{arg_name}': choices and min/max are mutually exclusive.\n"
+                f"Use either choices for discrete values or min/max for ranges, not both."
+            )
+
+    # Infer type from default, min, max, or choices if type not specified
+    if arg_type is None:
+        # Collect all values that can help infer type
+        inferred_types = []
+
+        if default is not None:
+            inferred_types.append(("default", _infer_variable_type(default)))
+        if min_val is not None:
+            inferred_types.append(("min", _infer_variable_type(min_val)))
+        if max_val is not None:
+            inferred_types.append(("max", _infer_variable_type(max_val)))
+        if choices is not None and len(choices) > 0:
+            inferred_types.append(("choices[0]", _infer_variable_type(choices[0])))
+
+        if inferred_types:
+            # Check all inferred types are consistent
+            first_name, first_type = inferred_types[0]
+            for value_name, value_type in inferred_types[1:]:
+                if value_type != first_type:
+                    # Build error message showing the conflicting types
+                    type_info = ", ".join([f"{name}={vtype}" for name, vtype in inferred_types])
+                    raise ValueError(
+                        f"Argument '{arg_name}': inconsistent types inferred from min, max, and default.\n"
+                        f"All values must have the same type.\n"
+                        f"Found: {type_info}"
+                    )
+
+            # All types are consistent, use the inferred type
+            arg_type = first_type
+        else:
+            # No values to infer from, default to string
+            arg_type = "str"
+    else:
+        # Explicit type was provided - validate that default matches it
+        # (min/max validation happens later, after the min/max numeric check)
+        if default is not None:
+            default_type = _infer_variable_type(default)
+            if default_type != explicit_type:
+                raise ValueError(
+                    f"Default value for argument '{arg_name}' is incompatible with type '{explicit_type}': "
+                    f"default has type '{default_type}'"
+                )
+
+    # Validate min/max are only used with numeric types
+    if (min_val is not None or max_val is not None) and arg_type not in ("int", "float"):
+        raise ValueError(
+            f"Argument '{arg_name}': min/max constraints are only supported for 'int' and 'float' types, "
+            f"not '{arg_type}'"
+        )
+
+    # If explicit type was provided, validate min/max match that type
+    if explicit_type is not None and arg_type in ("int", "float"):
+        type_mismatches = []
+        if min_val is not None:
+            min_type = _infer_variable_type(min_val)
+            if min_type != explicit_type:
+                type_mismatches.append(f"min value has type '{min_type}'")
+        if max_val is not None:
+            max_type = _infer_variable_type(max_val)
+            if max_type != explicit_type:
+                type_mismatches.append(f"max value has type '{max_type}'")
+
+        if type_mismatches:
+            raise ValueError(
+                f"Argument '{arg_name}': explicit type '{explicit_type}' does not match value types.\n"
+                + "\n".join([f"  - {mismatch}" for mismatch in type_mismatches])
+            )
+
+    # Validate min <= max
+    if min_val is not None and max_val is not None:
+        if min_val > max_val:
+            raise ValueError(
+                f"Argument '{arg_name}': min ({min_val}) must be less than or equal to max ({max_val})"
+            )
+
+    # Validate type name and get validator
+    try:
+        validator = get_click_type(arg_type)
+    except ValueError:
+        raise ValueError(
+            f"Unknown type in argument '{arg_name}': {arg_type}\n"
+            f"Supported types: str, int, float, bool, path, datetime, ip, ipv4, ipv6, email, hostname"
+        )
+
+    # Validate choices
+    if choices is not None:
+        # Boolean types cannot have choices
+        if arg_type == "bool":
+            raise ValueError(
+                f"Argument '{arg_name}': boolean types cannot have choices.\n"
+                f"Boolean values are already limited to true/false."
+            )
+
+        # Validate all choices are the same type
+        if len(choices) > 0:
+            first_choice_type = _infer_variable_type(choices[0])
+
+            # If explicit type was provided, validate choices match it
+            if explicit_type is not None and first_choice_type != explicit_type:
+                raise ValueError(
+                    f"Argument '{arg_name}': choice values do not match explicit type '{explicit_type}'.\n"
+                    f"First choice has type '{first_choice_type}'"
+                )
+
+            # Check all choices have the same type
+            for i, choice in enumerate(choices[1:], start=1):
+                choice_type = _infer_variable_type(choice)
+                if choice_type != first_choice_type:
+                    raise ValueError(
+                        f"Argument '{arg_name}': all choice values must have the same type.\n"
+                        f"First choice has type '{first_choice_type}', but choice at index {i} has type '{choice_type}'"
+                    )
+
+            # Validate all choices are valid for the type
+            for i, choice in enumerate(choices):
+                try:
+                    validator.convert(choice, None, None)
+                except Exception as e:
+                    raise ValueError(
+                        f"Argument '{arg_name}': choice at index {i} ({choice!r}) is invalid for type '{arg_type}': {e}"
+                    )
+
+    # Validate and convert default value
+    if default is not None:
+        # Validate that default is compatible with the declared type
+        if arg_type != "str":
+            # Validate that the default value is compatible with the type
+            try:
+                # Use the validator we already retrieved
+                converted_default = validator.convert(default, None, None)
+            except Exception as e:
+                raise ValueError(
+                    f"Default value for argument '{arg_name}' is incompatible with type '{arg_type}': {e}"
+                )
+
+            # Validate default is within min/max range
+            if min_val is not None and converted_default < min_val:
+                raise ValueError(
+                    f"Default value for argument '{arg_name}' ({default}) is less than min ({min_val})"
+                )
+            if max_val is not None and converted_default > max_val:
+                raise ValueError(
+                    f"Default value for argument '{arg_name}' ({default}) is greater than max ({max_val})"
+                )
+
+            # Validate default is in choices list
+            if choices is not None and converted_default not in choices:
+                raise ValueError(
+                    f"Default value for argument '{arg_name}' ({default}) is not in the choices list.\n"
+                    f"Valid choices: {choices}"
+                )
+
+            # After validation, convert to string for storage
+            default_str = str(default)
+        else:
+            # For string type, validate default is in choices
+            if choices is not None and default not in choices:
+                raise ValueError(
+                    f"Default value for argument '{arg_name}' ({default}) is not in the choices list.\n"
+                    f"Valid choices: {choices}"
+                )
+            default_str = str(default)
+    else:
+        # None remains None (not the string "None")
+        default_str = None
+
+    return ArgSpec(
+        name=arg_name,
+        arg_type=arg_type,
+        default=default_str,
+        is_exported=is_exported,
+        min_val=min_val,
+        max_val=max_val,
+        choices=choices
+    )