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

tasktree/cli.py

@@ -26,6 +26,41 @@ app = typer.Typer(
 console = Console()
 
 
+def _format_task_arguments(arg_specs: list[str | dict]) -> str:
+    """Format task arguments for display in list output.
+
+    Args:
+        arg_specs: List of argument specifications from task definition (strings or dicts)
+
+    Returns:
+        Formatted string showing arguments with types and defaults
+
+    Examples:
+        ["mode", "target"] -> "mode:str target:str"
+        ["mode=debug", "target=x86_64"] -> "mode:str [=debug] target:str [=x86_64]"
+        ["port:int", "debug:bool=false"] -> "port:int debug:bool [=false]"
+        [{"timeout": {"type": "int", "default": 30}}] -> "timeout:int [=30]"
+    """
+    if not arg_specs:
+        return ""
+
+    formatted_parts = []
+    for spec_str in arg_specs:
+        parsed = parse_arg_spec(spec_str)
+
+        # Format: name:type or name:type [=default]
+        # Argument names in normal intensity, types and defaults in dim
+        arg_part = f"{parsed.name}[dim]:{parsed.arg_type}[/dim]"
+
+        if parsed.default is not None:
+            # Use dim styling for the default value part
+            arg_part += f" [dim]\\[={parsed.default}][/dim]"
+
+        formatted_parts.append(arg_part)
+
+    return " ".join(formatted_parts)
+
+
 def _list_tasks(tasks_file: Optional[str] = None):
     """List all available tasks with descriptions."""
     recipe = _get_recipe(tasks_file)
@@ -33,14 +68,27 @@ def _list_tasks(tasks_file: Optional[str] = None):
         console.print("[red]No recipe file found (tasktree.yaml, tasktree.yml, tt.yaml, or *.tasks)[/red]")
         raise typer.Exit(1)
 
-    table = Table(title="Available Tasks")
-    table.add_column("Task", style="cyan", no_wrap=True)
-    table.add_column("Description", style="white")
+    # Calculate maximum task name length for fixed-width column
+    max_task_name_len = max(len(name) for name in recipe.task_names()) if recipe.task_names() else 0
+
+    # Create borderless table with three columns
+    table = Table(show_edge=False, show_header=False, box=None, padding=(0, 2))
+
+    # Command column: fixed width to accommodate longest task name
+    table.add_column("Command", style="bold cyan", no_wrap=True, width=max_task_name_len)
+
+    # Arguments column: allow wrapping with sensible max width
+    table.add_column("Arguments", style="white", max_width=60)
+
+    # Description column: allow wrapping with sensible max width
+    table.add_column("Description", style="white", max_width=80)
 
     for task_name in sorted(recipe.task_names()):
         task = recipe.get_task(task_name)
         desc = task.desc if task else ""
-        table.add_row(task_name, desc)
+        args_formatted = _format_task_arguments(task.args) if task else ""
+
+        table.add_row(task_name, args_formatted, desc)
 
     console.print(table)
 
@@ -351,9 +399,9 @@ def _execute_dynamic_task(args: list[str], force: bool = False, only: bool = Fal
     state.load()
     executor = Executor(recipe, state)
 
-    # Prune state before execution (compute hashes with effective environment)
+    # Prune state before execution (compute hashes with effective environment and dependencies)
     valid_hashes = {
-        hash_task(t.cmd, t.outputs, t.working_dir, t.args, executor._get_effective_env_name(t))
+        hash_task(t.cmd, t.outputs, t.working_dir, t.args, executor._get_effective_env_name(t), t.deps)
         for t in recipe.tasks.values()
     }
     state.prune(valid_hashes)

tasktree/docker.py

@@ -87,16 +87,24 @@ class DockerManager:
 
         # Build the image
         try:
+            docker_build_cmd = [
+                "docker",
+                "build",
+                "-t",
+                image_tag,
+                "-f",
+                str(dockerfile_path),
+            ]
+
+            # Add build args if environment has them (docker environments use dict for args)
+            if isinstance(env.args, dict):
+                for arg_name, arg_value in env.args.items():
+                    docker_build_cmd.extend(["--build-arg", f"{arg_name}={arg_value}"])
+
+            docker_build_cmd.append(str(context_path))
+
             subprocess.run(
-                [
-                    "docker",
-                    "build",
-                    "-t",
-                    image_tag,
-                    "-f",
-                    str(dockerfile_path),
-                    str(context_path),
-                ],
+                docker_build_cmd,
                 check=True,
                 capture_output=False,  # Show build output to user
             )

tasktree/executor.py

@@ -64,6 +64,62 @@ class Executor:
         self.state = state_manager
         self.docker_manager = docker_module.DockerManager(recipe.project_root)
 
+    def _has_regular_args(self, task: Task) -> bool:
+        """Check if a task has any regular (non-exported) arguments.
+
+        Args:
+            task: Task to check
+
+        Returns:
+            True if task has at least one regular (non-exported) argument, False otherwise
+        """
+        if not task.args:
+            return False
+
+        # Check if any arg is not exported (doesn't start with $)
+        for arg_spec in task.args:
+            # Handle both string and dict arg specs
+            if isinstance(arg_spec, str):
+                # Remove default value part if present
+                arg_name = arg_spec.split('=')[0].split(':')[0].strip()
+                if not arg_name.startswith('$'):
+                    return True
+            elif isinstance(arg_spec, dict):
+                # Dict format: { argname: { ... } } or { $argname: { ... } }
+                for key in arg_spec.keys():
+                    if not key.startswith('$'):
+                        return True
+
+        return False
+
+    def _filter_regular_args(self, task: Task, task_args: dict[str, Any]) -> dict[str, Any]:
+        """Filter task_args to only include regular (non-exported) arguments.
+
+        Args:
+            task: Task definition
+            task_args: Dictionary of all task arguments
+
+        Returns:
+            Dictionary containing only regular (non-exported) arguments
+        """
+        if not task.args or not task_args:
+            return {}
+
+        # Build set of exported arg names (without the $ prefix)
+        exported_names = set()
+        for arg_spec in task.args:
+            if isinstance(arg_spec, str):
+                arg_name = arg_spec.split('=')[0].split(':')[0].strip()
+                if arg_name.startswith('$'):
+                    exported_names.add(arg_name[1:])  # Remove $ prefix
+            elif isinstance(arg_spec, dict):
+                for key in arg_spec.keys():
+                    if key.startswith('$'):
+                        exported_names.add(key[1:])  # Remove $ prefix
+
+        # Filter out exported args
+        return {k: v for k, v in task_args.items() if k not in exported_names}
+
     def _collect_early_builtin_variables(self, task: Task, timestamp: datetime) -> dict[str, str]:
         """Collect built-in variables that don't depend on working_dir.
 
@@ -277,9 +333,9 @@ class Executor:
                 reason="forced",
             )
 
-        # Compute hashes (include effective environment)
+        # Compute hashes (include effective environment and dependencies)
         effective_env = self._get_effective_env_name(task)
-        task_hash = hash_task(task.cmd, task.outputs, task.working_dir, task.args, effective_env)
+        task_hash = hash_task(task.cmd, task.outputs, task.working_dir, task.args, effective_env, task.deps)
         args_hash = hash_args(args_dict) if args_dict else None
         cache_key = make_cache_key(task_hash, args_hash)
 
@@ -372,22 +428,39 @@ class Executor:
         # Resolve execution order
         if only:
             # Only execute the target task, skip dependencies
-            execution_order = [task_name]
+            execution_order = [(task_name, args_dict)]
         else:
             # Execute task and all dependencies
-            execution_order = resolve_execution_order(self.recipe, task_name)
+            execution_order = resolve_execution_order(self.recipe, task_name, args_dict)
 
         # Single phase: Check and execute incrementally
         statuses: dict[str, TaskStatus] = {}
-        for name in execution_order:
+        for name, task_args in execution_order:
             task = self.recipe.tasks[name]
 
-            # Determine task-specific args (only for target task)
-            task_args = args_dict if name == task_name else {}
+            # Convert None to {} for internal use (None is used to distinguish simple deps in graph)
+            args_dict_for_execution = task_args if task_args is not None else {}
 
             # Check if task needs to run (based on CURRENT filesystem state)
-            status = self.check_task_status(task, task_args, force=force)
-            statuses[name] = status
+            status = self.check_task_status(task, args_dict_for_execution, force=force)
+
+            # Use a key that includes args for status tracking
+            # Only include regular (non-exported) args in status key for parameterized dependencies
+            # For the root task (invoked from CLI), status key is always just the task name
+            # For dependencies with parameterized invocations, include the regular args
+            is_root_task = (name == task_name)
+            if not is_root_task and args_dict_for_execution and self._has_regular_args(task):
+                import json
+                # Filter to only include regular (non-exported) args
+                regular_args = self._filter_regular_args(task, args_dict_for_execution)
+                if regular_args:
+                    args_str = json.dumps(regular_args, sort_keys=True, separators=(",", ":"))
+                    status_key = f"{name}({args_str})"
+                else:
+                    status_key = name
+            else:
+                status_key = name
+            statuses[status_key] = status
 
             # Execute immediately if needed
             if status.will_run:
@@ -399,7 +472,7 @@ class Executor:
                         file=sys.stderr,
                     )
 
-                self._run_task(task, task_args)
+                self._run_task(task, args_dict_for_execution)
 
         return statuses
 
@@ -962,9 +1035,9 @@ class Executor:
             task: Task that was executed
             args_dict: Arguments used for execution
         """
-        # Compute hashes (include effective environment)
+        # Compute hashes (include effective environment and dependencies)
         effective_env = self._get_effective_env_name(task)
-        task_hash = hash_task(task.cmd, task.outputs, task.working_dir, task.args, effective_env)
+        task_hash = hash_task(task.cmd, task.outputs, task.working_dir, task.args, effective_env, task.deps)
         args_hash = hash_args(args_dict) if args_dict else None
         cache_key = make_cache_key(task_hash, args_hash)
 

tasktree/graph.py

@@ -2,8 +2,10 @@
 
 from graphlib import TopologicalSorter
 from pathlib import Path
+from typing import Any
 
-from tasktree.parser import Recipe, Task
+from tasktree.hasher import hash_args
+from tasktree.parser import Recipe, Task, DependencyInvocation, parse_dependency_spec
 
 
 class CycleError(Exception):
@@ -18,15 +20,61 @@ class TaskNotFoundError(Exception):
     pass
 
 
-def resolve_execution_order(recipe: Recipe, target_task: str) -> list[str]:
+class TaskNode:
+    """Represents a node in the dependency graph (task + arguments).
+
+    Each node represents a unique invocation of a task with specific arguments.
+    Tasks invoked with different arguments are considered different nodes.
+    """
+
+    def __init__(self, task_name: str, args: dict[str, Any] | None = None):
+        self.task_name = task_name
+        self.args = args  # Keep None as None
+
+    def __hash__(self):
+        """Hash based on task name and sorted args."""
+        # Treat None and {} as equivalent for hashing
+        if not self.args:
+            return hash(self.task_name)
+        args_hash = hash_args(self.args)
+        return hash((self.task_name, args_hash))
+
+    def __eq__(self, other):
+        """Equality based on task name and args."""
+        if not isinstance(other, TaskNode):
+            return False
+        # Treat None and {} as equivalent
+        self_args = self.args if self.args else {}
+        other_args = other.args if other.args else {}
+        return self.task_name == other.task_name and self_args == other_args
+
+    def __repr__(self):
+        if not self.args:
+            return f"TaskNode({self.task_name})"
+        args_str = ", ".join(f"{k}={v}" for k, v in sorted(self.args.items()))
+        return f"TaskNode({self.task_name}, {{{args_str}}})"
+
+    def __str__(self):
+        if not self.args:
+            return self.task_name
+        args_str = ", ".join(f"{k}={v}" for k, v in sorted(self.args.items()))
+        return f"{self.task_name}({args_str})"
+
+
+def resolve_execution_order(
+    recipe: Recipe,
+    target_task: str,
+    target_args: dict[str, Any] | None = None
+) -> list[tuple[str, dict[str, Any]]]:
     """Resolve execution order for a task and its dependencies.
 
     Args:
         recipe: Parsed recipe containing all tasks
         target_task: Name of the task to execute
+        target_args: Arguments for the target task (optional)
 
     Returns:
-        List of task names in execution order (dependencies first)
+        List of (task_name, args_dict) tuples in execution order (dependencies first)
 
     Raises:
         TaskNotFoundError: If target task or any dependency doesn't exist
@@ -35,33 +83,61 @@ def resolve_execution_order(recipe: Recipe, target_task: str) -> list[str]:
     if target_task not in recipe.tasks:
         raise TaskNotFoundError(f"Task not found: {target_task}")
 
-    # Build dependency graph
-    graph: dict[str, set[str]] = {}
+    # Build dependency graph using TaskNode objects
+    graph: dict[TaskNode, set[TaskNode]] = {}
+
+    # Track seen nodes to detect duplicates
+    seen_invocations: dict[tuple[str, str], TaskNode] = {}  # (task_name, args_hash) -> node
 
-    def build_graph(task_name: str) -> None:
+    def get_or_create_node(task_name: str, args: dict[str, Any] | None) -> TaskNode:
+        """Get existing node or create new one for this invocation."""
+        args_hash = hash_args(args) if args else ""
+        key = (task_name, args_hash)
+
+        if key not in seen_invocations:
+            seen_invocations[key] = TaskNode(task_name, args)
+        return seen_invocations[key]
+
+    def build_graph(node: TaskNode) -> None:
         """Recursively build dependency graph."""
-        if task_name in graph:
+        if node in graph:
             # Already processed
             return
 
-        task = recipe.tasks.get(task_name)
+        task = recipe.tasks.get(node.task_name)
         if task is None:
-            raise TaskNotFoundError(f"Task not found: {task_name}")
+            raise TaskNotFoundError(f"Task not found: {node.task_name}")
 
-        # Add task to graph with its dependencies
-        graph[task_name] = set(task.deps)
+        # Parse and normalize dependencies
+        dep_nodes = set()
+        for dep_spec in task.deps:
+            # Parse dependency specification
+            dep_inv = parse_dependency_spec(dep_spec, recipe)
+
+            # Create or get node for this dependency invocation
+            dep_node = get_or_create_node(dep_inv.task_name, dep_inv.args)
+            dep_nodes.add(dep_node)
+
+        # Add task to graph with its dependency nodes
+        graph[node] = dep_nodes
 
         # Recursively process dependencies
-        for dep in task.deps:
-            build_graph(dep)
+        for dep_node in dep_nodes:
+            build_graph(dep_node)
+
+    # Create root node for target task
+    root_node = get_or_create_node(target_task, target_args)
 
     # Build graph starting from target task
-    build_graph(target_task)
+    build_graph(root_node)
 
     # Use TopologicalSorter to resolve execution order
     try:
         sorter = TopologicalSorter(graph)
-        return list(sorter.static_order())
+        ordered_nodes = list(sorter.static_order())
+
+        # Convert TaskNode objects to (task_name, args_dict) tuples
+        return [(node.task_name, node.args) for node in ordered_nodes]
     except ValueError as e:
         raise CycleError(f"Dependency cycle detected: {e}")
 
@@ -87,8 +163,10 @@ def get_implicit_inputs(recipe: Recipe, task: Task) -> list[str]:
     implicit_inputs = []
 
     # Inherit from dependencies
-    for dep_name in task.deps:
-        dep_task = recipe.tasks.get(dep_name)
+    for dep_spec in task.deps:
+        # Parse dependency to get task name (ignore args for input inheritance)
+        dep_inv = parse_dependency_spec(dep_spec, recipe)
+        dep_task = recipe.tasks.get(dep_inv.task_name)
         if dep_task is None:
             continue
 
@@ -125,7 +203,7 @@ def get_implicit_inputs(recipe: Recipe, task: Task) -> list[str]:
     return implicit_inputs
 
 
-def build_dependency_tree(recipe: Recipe, target_task: str) -> dict:
+def build_dependency_tree(recipe: Recipe, target_task: str, target_args: dict[str, Any] | None = None) -> dict:
     """Build a tree structure representing dependencies for visualization.
 
     Note: This builds a true tree representation where shared dependencies may
@@ -135,6 +213,7 @@ def build_dependency_tree(recipe: Recipe, target_task: str) -> dict:
     Args:
         recipe: Parsed recipe containing all tasks
         target_task: Name of the task to build tree for
+        target_args: Arguments for the target task (optional)
 
     Returns:
         Nested dictionary representing the dependency tree
@@ -144,25 +223,44 @@ def build_dependency_tree(recipe: Recipe, target_task: str) -> dict:
 
     current_path = set()  # Track current recursion path for cycle detection
 
-    def build_tree(task_name: str) -> dict:
+    def build_tree(task_name: str, args: dict[str, Any] | None) -> dict:
         """Recursively build dependency tree."""
         task = recipe.tasks.get(task_name)
         if task is None:
             raise TaskNotFoundError(f"Task not found: {task_name}")
 
+        # Create node identifier for cycle detection
+        from tasktree.hasher import hash_args
+        args_dict = args or {}
+        node_id = (task_name, hash_args(args_dict) if args_dict else "")
+
         # Detect cycles in current recursion path
-        if task_name in current_path:
-            return {"name": task_name, "deps": [], "cycle": True}
+        if node_id in current_path:
+            display_name = task_name if not args_dict else f"{task_name}({', '.join(f'{k}={v}' for k, v in sorted(args_dict.items()))})"
+            return {"name": display_name, "deps": [], "cycle": True}
+
+        current_path.add(node_id)
+
+        # Parse dependencies
+        dep_trees = []
+        for dep_spec in task.deps:
+            dep_inv = parse_dependency_spec(dep_spec, recipe)
+            dep_tree = build_tree(dep_inv.task_name, dep_inv.args)
+            dep_trees.append(dep_tree)
 
-        current_path.add(task_name)
+        # Create display name (include args if present)
+        display_name = task_name
+        if args_dict:
+            args_str = ", ".join(f"{k}={v}" for k, v in sorted(args_dict.items()))
+            display_name = f"{task_name}({args_str})"
 
         tree = {
-            "name": task_name,
-            "deps": [build_tree(dep) for dep in task.deps],
+            "name": display_name,
+            "deps": dep_trees,
         }
 
-        current_path.remove(task_name)
+        current_path.remove(node_id)
 
         return tree
 
-    return build_tree(target_task)
+    return build_tree(target_task, target_args)

tasktree/hasher.py

@@ -37,7 +37,27 @@ def _normalize_choices_lists(args: list[str | dict[str, Any]]) ->  list[str | di
     return normalized_args
 
 
-def hash_task(cmd: str, outputs: list[str], working_dir: str, args: list[str | dict[str, Any]], env: str = "") -> str:
+def hash_task(
+    cmd: str,
+    outputs: list[str],
+    working_dir: str,
+    args: list[str | dict[str, Any]],
+    env: str = "",
+    deps: list[str | dict[str, Any]] | None = None
+) -> str:
+    """Hash task definition including dependencies.
+
+    Args:
+        cmd: Task command
+        outputs: Task outputs
+        working_dir: Working directory
+        args: Task argument specifications
+        env: Environment name
+        deps: Dependency specifications (optional, for dependency hash)
+
+    Returns:
+        8-character hash of task definition
+    """
     data = {
         "cmd": cmd,
         "outputs": sorted(outputs),
@@ -46,6 +66,23 @@ def hash_task(cmd: str, outputs: list[str], working_dir: str, args: list[str | d
         "env": env,
     }
 
+    # Include dependency invocation signatures if provided
+    if deps is not None:
+        # Normalize deps for hashing using JSON serialization for consistency
+        normalized_deps = []
+        for dep in deps:
+            if isinstance(dep, str):
+                # Simple string dependency
+                normalized_deps.append(dep)
+            elif isinstance(dep, dict):
+                # Dict dependency with args - normalize to canonical form
+                # Sort the dict to ensure consistent hashing
+                normalized_deps.append(dict(sorted(dep.items())))
+            else:
+                normalized_deps.append(dep)
+        # Sort using JSON serialization for consistent ordering
+        data["deps"] = sorted(normalized_deps, key=lambda x: json.dumps(x, sort_keys=True) if isinstance(x, dict) else x)
+
     serialized = json.dumps(data, sort_keys=True, separators=(",", ":"))
     return hashlib.sha256(serialized.encode()).hexdigest()[:8]
 
@@ -67,9 +104,16 @@ def hash_environment_definition(env) -> str:
     # Import inside function to avoid circular dependency
     from tasktree.parser import Environment
 
+    # Handle args - can be list (shell args) or dict (docker build args)
+    args_value = env.args
+    if isinstance(env.args, dict):
+        args_value = dict(sorted(env.args.items()))  # Sort dict for determinism
+    elif isinstance(env.args, list):
+        args_value = sorted(env.args)  # Sort list for determinism
+
     data = {
         "shell": env.shell,
-        "args": sorted(env.args),  # Sort for determinism
+        "args": args_value,
         "preamble": env.preamble,
         "dockerfile": env.dockerfile,
         "context": env.context,

tasktree/parser.py

@@ -31,7 +31,7 @@ class Environment:
 
     name: str
     shell: str = ""  # Path to shell (required for shell envs, optional for Docker)
-    args: list[str] = field(default_factory=list)
+    args: list[str] | dict[str, str] = field(default_factory=list)  # Shell args (list) or Docker build args (dict)
     preamble: str = ""
     # Docker-specific fields (presence of dockerfile indicates Docker environment)
     dockerfile: str = ""  # Path to Dockerfile
@@ -44,7 +44,7 @@ class Environment:
     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."""
+        """Ensure args is in the correct format."""
         if isinstance(self.args, str):
             self.args = [self.args]
 
@@ -56,11 +56,11 @@ class Task:
     name: str
     cmd: str
     desc: str = ""
-    deps: list[str] = field(default_factory=list)
+    deps: list[str | dict[str, Any]] = field(default_factory=list)  # Can be strings or dicts with args
     inputs: list[str] = field(default_factory=list)
     outputs: list[str] = field(default_factory=list)
     working_dir: str = ""
-    args: list[str] = field(default_factory=list)
+    args: list[str | dict[str, Any]] = field(default_factory=list)  # Can be strings or dicts (each dict has single key: arg name)
     source_file: str = ""  # Track which file defined this task
     env: str = ""  # Environment name to use for execution
 
@@ -75,6 +75,38 @@ class Task:
         if isinstance(self.args, str):
             self.args = [self.args]
 
+        # Validate args is not a dict (common YAML mistake)
+        if isinstance(self.args, dict):
+            raise ValueError(
+                f"Task '{self.name}' has invalid 'args' syntax.\n\n"
+                f"Found dictionary syntax (without dashes):\n"
+                f"  args:\n"
+                f"    {list(self.args.keys())[0] if self.args else 'key'}: ...\n\n"
+                f"Correct syntax uses list format (with dashes):\n"
+                f"  args:\n"
+                f"    - {list(self.args.keys())[0] if self.args else 'key'}: ...\n\n"
+                f"Arguments must be defined as a list, not a dictionary."
+            )
+
+
+@dataclass
+class DependencyInvocation:
+    """Represents a task dependency invocation with optional arguments.
+
+    Attributes:
+        task_name: Name of the dependency task
+        args: Dictionary of argument names to values (None if no args specified)
+    """
+    task_name: str
+    args: dict[str, Any] | None = None
+
+    def __str__(self) -> str:
+        """String representation for display."""
+        if not self.args:
+            return self.task_name
+        args_str = ", ".join(f"{k}={v}" for k, v in self.args.items())
+        return f"{self.task_name}({args_str})"
+
 
 @dataclass
 class ArgSpec:
@@ -731,10 +763,16 @@ def _resolve_variable_value(
         # Validate and stringify the value
         string_value = validator.convert(raw_value, None, None)
 
+        # Convert to string (lowercase for booleans to match YAML/shell conventions)
+        if isinstance(string_value, bool):
+            string_value_str = str(string_value).lower()
+        else:
+            string_value_str = str(string_value)
+
         # Substitute any {{ var.name }} references in the string value
         from tasktree.substitution import substitute_variables
         try:
-            resolved_value = substitute_variables(str(string_value), resolved)
+            resolved_value = substitute_variables(string_value_str, resolved)
         except ValueError as e:
             # Check if the undefined variable is in the resolution stack (circular reference)
             error_msg = str(e)
@@ -1117,18 +1155,40 @@ def _parse_file(
             # 2. It starts with a local import namespace (like "base.setup" when "base" is imported)
             rewritten_deps = []
             for dep in deps:
-                if "." not in dep:
-                    # Simple name - always prefix
-                    rewritten_deps.append(f"{namespace}.{dep}")
-                else:
-                    # Check if it starts with a local import namespace
-                    dep_root = dep.split(".", 1)[0]
-                    if dep_root in local_import_namespaces:
-                        # Local import reference - prefix it
+                if isinstance(dep, str):
+                    # Simple string dependency
+                    if "." not in dep:
+                        # Simple name - always prefix
                         rewritten_deps.append(f"{namespace}.{dep}")
                     else:
-                        # External reference - keep as-is
-                        rewritten_deps.append(dep)
+                        # Check if it starts with a local import namespace
+                        dep_root = dep.split(".", 1)[0]
+                        if dep_root in local_import_namespaces:
+                            # Local import reference - prefix it
+                            rewritten_deps.append(f"{namespace}.{dep}")
+                        else:
+                            # External reference - keep as-is
+                            rewritten_deps.append(dep)
+                elif isinstance(dep, dict):
+                    # Dict dependency with args - rewrite the task name key
+                    rewritten_dep = {}
+                    for task_name, args in dep.items():
+                        if "." not in task_name:
+                            # Simple name - prefix it
+                            rewritten_dep[f"{namespace}.{task_name}"] = args
+                        else:
+                            # Check if it starts with a local import namespace
+                            dep_root = task_name.split(".", 1)[0]
+                            if dep_root in local_import_namespaces:
+                                # Local import reference - prefix it
+                                rewritten_dep[f"{namespace}.{task_name}"] = args
+                            else:
+                                # External reference - keep as-is
+                                rewritten_dep[task_name] = args
+                    rewritten_deps.append(rewritten_dep)
+                else:
+                    # Unknown type - keep as-is
+                    rewritten_deps.append(dep)
             deps = rewritten_deps
 
         task = Task(
@@ -1539,3 +1599,208 @@ def _parse_arg_dict(arg_name: str, config: dict, is_exported: bool) -> ArgSpec:
         max_val=max_val,
         choices=choices
     )
+
+
+def parse_dependency_spec(dep_spec: str | dict[str, Any], recipe: Recipe) -> DependencyInvocation:
+    """Parse a dependency specification into a DependencyInvocation.
+
+    Supports three forms:
+    1. Simple string: "task_name" -> DependencyInvocation(task_name, None)
+    2. Positional args: {"task_name": [arg1, arg2]} -> DependencyInvocation(task_name, {name1: arg1, name2: arg2})
+    3. Named args: {"task_name": {arg1: val1}} -> DependencyInvocation(task_name, {arg1: val1})
+
+    Args:
+        dep_spec: Dependency specification (string or dict)
+        recipe: Recipe containing task definitions (for arg normalization)
+
+    Returns:
+        DependencyInvocation object with normalized args
+
+    Raises:
+        ValueError: If dependency specification is invalid
+    """
+    # Simple string case
+    if isinstance(dep_spec, str):
+        return DependencyInvocation(task_name=dep_spec, args=None)
+
+    # Dictionary case
+    if not isinstance(dep_spec, dict):
+        raise ValueError(
+            f"Dependency must be a string or dictionary, got: {type(dep_spec).__name__}"
+        )
+
+    # Validate dict has exactly one key
+    if len(dep_spec) != 1:
+        raise ValueError(
+            f"Dependency dictionary must have exactly one key (the task name), got: {list(dep_spec.keys())}"
+        )
+
+    task_name, arg_spec = next(iter(dep_spec.items()))
+
+    # Validate task name
+    if not isinstance(task_name, str) or not task_name:
+        raise ValueError(
+            f"Dependency task name must be a non-empty string, got: {task_name!r}"
+        )
+
+    # Check for empty list (explicitly disallowed)
+    if isinstance(arg_spec, list) and len(arg_spec) == 0:
+        raise ValueError(
+            f"Empty argument list for dependency '{task_name}' is not allowed.\n"
+            f"Use simple string form instead: '{task_name}'"
+        )
+
+    # Positional args (list)
+    if isinstance(arg_spec, list):
+        return _parse_positional_dependency_args(task_name, arg_spec, recipe)
+
+    # Named args (dict)
+    if isinstance(arg_spec, dict):
+        return _parse_named_dependency_args(task_name, arg_spec, recipe)
+
+    # Invalid type
+    raise ValueError(
+        f"Dependency arguments for '{task_name}' must be a list (positional) or dict (named), "
+        f"got: {type(arg_spec).__name__}"
+    )
+
+
+def _get_validated_task(task_name: str, recipe: Recipe) -> Task:
+    """Get and validate that a task exists in the recipe.
+
+    Args:
+        task_name: Name of the task to retrieve
+        recipe: Recipe containing task definitions
+
+    Returns:
+        The validated Task object
+
+    Raises:
+        ValueError: If task is not found
+    """
+    task = recipe.get_task(task_name)
+    if task is None:
+        raise ValueError(f"Dependency task not found: {task_name}")
+    return task
+
+
+def _parse_positional_dependency_args(
+    task_name: str, args_list: list[Any], recipe: Recipe
+) -> DependencyInvocation:
+    """Parse positional dependency arguments.
+
+    Args:
+        task_name: Name of the dependency task
+        args_list: List of positional argument values
+        recipe: Recipe containing task definitions
+
+    Returns:
+        DependencyInvocation with normalized named args
+
+    Raises:
+        ValueError: If validation fails
+    """
+    # Get the task to validate against
+    task = _get_validated_task(task_name, recipe)
+
+    # Parse task's arg specs
+    if not task.args:
+        raise ValueError(
+            f"Task '{task_name}' takes no arguments, but {len(args_list)} were provided"
+        )
+
+    parsed_specs = [parse_arg_spec(spec) for spec in task.args]
+
+    # Check positional count doesn't exceed task's arg count
+    if len(args_list) > len(parsed_specs):
+        raise ValueError(
+            f"Task '{task_name}' takes {len(parsed_specs)} arguments, got {len(args_list)}"
+        )
+
+    # Map positional args to names with type conversion
+    args_dict = {}
+    for i, value in enumerate(args_list):
+        spec = parsed_specs[i]
+        if isinstance(value, str):
+            # Convert string values using type validator
+            click_type = get_click_type(spec.arg_type, min_val=spec.min_val, max_val=spec.max_val)
+            args_dict[spec.name] = click_type.convert(value, None, None)
+        else:
+            # Value is already typed (e.g., bool, int from YAML)
+            args_dict[spec.name] = value
+
+    # Fill in defaults for remaining args
+    for i in range(len(args_list), len(parsed_specs)):
+        spec = parsed_specs[i]
+        if spec.default is not None:
+            # Defaults in task specs are always strings, convert them
+            click_type = get_click_type(spec.arg_type, min_val=spec.min_val, max_val=spec.max_val)
+            args_dict[spec.name] = click_type.convert(spec.default, None, None)
+        else:
+            raise ValueError(
+                f"Task '{task_name}' requires argument '{spec.name}' (no default provided)"
+            )
+
+    return DependencyInvocation(task_name=task_name, args=args_dict)
+
+
+def _parse_named_dependency_args(
+    task_name: str, args_dict: dict[str, Any], recipe: Recipe
+) -> DependencyInvocation:
+    """Parse named dependency arguments.
+
+    Args:
+        task_name: Name of the dependency task
+        args_dict: Dictionary of argument names to values
+        recipe: Recipe containing task definitions
+
+    Returns:
+        DependencyInvocation with normalized args (defaults filled)
+
+    Raises:
+        ValueError: If validation fails
+    """
+    # Get the task to validate against
+    task = _get_validated_task(task_name, recipe)
+
+    # Parse task's arg specs
+    if not task.args:
+        if args_dict:
+            raise ValueError(
+                f"Task '{task_name}' takes no arguments, but {len(args_dict)} were provided"
+            )
+        return DependencyInvocation(task_name=task_name, args={})
+
+    parsed_specs = [parse_arg_spec(spec) for spec in task.args]
+    spec_map = {spec.name: spec for spec in parsed_specs}
+
+    # Validate all provided arg names exist
+    for arg_name in args_dict:
+        if arg_name not in spec_map:
+            raise ValueError(
+                f"Task '{task_name}' has no argument named '{arg_name}'"
+            )
+
+    # Build normalized args dict with defaults
+    normalized_args = {}
+    for spec in parsed_specs:
+        if spec.name in args_dict:
+            # Use provided value with type conversion (only convert strings)
+            value = args_dict[spec.name]
+            if isinstance(value, str):
+                click_type = get_click_type(spec.arg_type, min_val=spec.min_val, max_val=spec.max_val)
+                normalized_args[spec.name] = click_type.convert(value, None, None)
+            else:
+                # Value is already typed (e.g., bool, int from YAML)
+                normalized_args[spec.name] = value
+        elif spec.default is not None:
+            # Use default value (defaults are always strings in task specs)
+            click_type = get_click_type(spec.arg_type, min_val=spec.min_val, max_val=spec.max_val)
+            normalized_args[spec.name] = click_type.convert(spec.default, None, None)
+        else:
+            # Required arg not provided
+            raise ValueError(
+                f"Task '{task_name}' requires argument '{spec.name}' (no default provided)"
+            )
+
+    return DependencyInvocation(task_name=task_name, args=normalized_args)

tasktree/substitution.py

@@ -87,8 +87,11 @@ def substitute_arguments(text: str, args: dict[str, Any], exported_args: set[str
                 f"Required arguments must be provided."
             )
 
-        # Convert to string
-        return str(args[name])
+        # Convert to string (lowercase for booleans to match YAML/shell conventions)
+        value = args[name]
+        if isinstance(value, bool):
+            return str(value).lower()
+        return str(value)
 
     return PLACEHOLDER_PATTERN.sub(replace_match, text)
 

{tasktree-0.0.8.dist-info → tasktree-0.0.10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tasktree
-Version: 0.0.8
+Version: 0.0.10
 Summary: A task automation tool with incremental execution
 Requires-Python: >=3.11
 Requires-Dist: click>=8.1.0
@@ -594,6 +594,97 @@ If an exported argument with a default isn't available as an environment variabl
 2. The CLI automatically applies defaults before execution
 3. You can explicitly provide the value: `tt deploy prod-server port=8080`
 
+### Parameterized Dependencies
+
+Dependencies can invoke tasks with specific arguments, enabling flexible and reusable task graphs:
+
+**Syntax:**
+
+```yaml
+tasks:
+  # Task with parameters
+  process:
+    args: [mode, verbose=false]
+    cmd: echo "mode={{arg.mode}} verbose={{arg.verbose}}"
+
+  # Simple dependency (uses defaults)
+  consumer1:
+    deps: [process]  # Equivalent to: process(mode must be provided)
+    cmd: echo "done"
+
+  # Positional arguments
+  consumer2:
+    deps:
+      - process: [debug, true]  # Maps to: mode=debug, verbose=true
+    cmd: echo "done"
+
+  # Named arguments
+  consumer3:
+    deps:
+      - process: {mode: release, verbose: false}
+    cmd: echo "done"
+
+  # Multiple invocations with different args
+  multi_build:
+    deps:
+      - process: [debug]
+      - process: [release]
+    cmd: echo "All builds complete"
+```
+
+**Key behaviors:**
+
+- **Simple string form** (`- task_name`): Uses task defaults for all arguments. Required arguments must have defaults or task invocation fails.
+- **Positional form** (`- task_name: [arg1, arg2]`): Arguments mapped by position. Can omit trailing args if they have defaults.
+- **Named form** (`- task_name: {arg1: val1}`): Arguments mapped by name. Can omit any arg with a default.
+- **Multiple invocations**: Same task with different arguments creates separate graph nodes, each executing independently.
+- **Normalization**: All forms normalized to named arguments with defaults filled before execution.
+- **Cache separation**: `process(debug)` and `process(release)` cache independently.
+
+**Restrictions:**
+
+- **No empty lists**: `- task: []` is invalid (use `- task` instead)
+- **No mixed positional and named**: Choose one form per dependency
+- **Single-key dicts**: `{task1: [x], task2: [y]}` is invalid (multi-key not allowed)
+
+**Validation:**
+
+Validation happens at graph construction time with clear error messages:
+
+```
+Task 'process' takes 2 arguments, got 3
+Task 'build' has no argument named 'mode'
+Task 'deploy' requires argument 'environment' (no default provided)
+```
+
+**Example use cases:**
+
+```yaml
+tasks:
+  # Compile for different platforms
+  compile:
+    args: [target]
+    cmd: cargo build --target {{arg.target}}
+
+  dist:
+    deps:
+      - compile: [x86_64-unknown-linux-gnu]
+      - compile: [aarch64-unknown-linux-gnu]
+    cmd: tar czf dist.tar.gz target/*/release/app
+
+  # Run tests with different configurations
+  test:
+    args: [config]
+    cmd: pytest --config={{arg.config}}
+
+  ci:
+    deps:
+      - test: [unit]
+      - test: [integration]
+      - test: [e2e]
+    cmd: echo "All tests passed"
+```
+
 ## Environment Variables
 
 Task Tree supports reading environment variables in two ways:

tasktree-0.0.10.dist-info/RECORD

@@ -0,0 +1,15 @@
+tasktree/__init__.py,sha256=MVmdvKb3JdqLlo0x2_TPGMfgFC0HsDnP79HAzGnFnjI,1081
+tasktree/cli.py,sha256=H5T8wOxLBGx-ZTQEnkoJrX3srgD5b_7BLf1IWl18M2M,17597
+tasktree/docker.py,sha256=qvja8G63uAcC73YMVY739egda1_CcBtoqzm0qIJU_Q8,14443
+tasktree/executor.py,sha256=Q7Bks5B88i-IyZDpxGSps9MM3uflz0U3yn4Rtq_uHMM,42266
+tasktree/graph.py,sha256=oXLxX0Ix4zSkVBg8_3x9K7WxSFpg136sp4MF-d2mDEQ,9682
+tasktree/hasher.py,sha256=0GrnCfwAXnwq_kpnHFFb12B5_2VFNXx6Ng7hTdcCyXo,4415
+tasktree/parser.py,sha256=N_dXHl5UF0rBvIVdbsVZOo5Ur5uFEKgY1sSPNfScTxc,67135
+tasktree/state.py,sha256=Cktl4D8iDZVd55aO2LqVyPrc-BnljkesxxkcMcdcfOY,3541
+tasktree/substitution.py,sha256=M_qcP0NKJATrKcNShSqHJatneuth1RVwTk1ci8-ZuxQ,6473
+tasktree/tasks.py,sha256=2QdQZtJAX2rSGbyXKG1z9VF_siz1DUzdvzCgPkykxtU,173
+tasktree/types.py,sha256=R_YAyO5bMLB6XZnkMRT7VAtlkA_Xx6xu0aIpzQjrBXs,4357
+tasktree-0.0.10.dist-info/METADATA,sha256=JyhF89pfUwr0bkV33rNae-0ytPyOEr2bKHfiWN-YsK0,37124
+tasktree-0.0.10.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+tasktree-0.0.10.dist-info/entry_points.txt,sha256=lQINlvRYnimvteBbnhH84A9clTg8NnpEjCWqWkqg8KE,40
+tasktree-0.0.10.dist-info/RECORD,,

tasktree-0.0.8.dist-info/RECORD

@@ -1,15 +0,0 @@
-tasktree/__init__.py,sha256=MVmdvKb3JdqLlo0x2_TPGMfgFC0HsDnP79HAzGnFnjI,1081
-tasktree/cli.py,sha256=bPojvR7kS2iQomNFSykYsrOgD4Nc5XAH4XbEfdVL9qk,15736
-tasktree/docker.py,sha256=R69NcZw4MyaxEXyJAwniYCm877iaI10jRhxlLmkA6Fs,14119
-tasktree/executor.py,sha256=iZ_BF3pjyxhH6l2p78rLSK54Xk-V08Ae_BVF6CIi3jo,38979
-tasktree/graph.py,sha256=lA3ExNM_ag0AlC6iW20unseCjRg5wCZXbmXs2M6TnQw,5578
-tasktree/hasher.py,sha256=S4OKsNjf1ZnhGAvRWr6usuAudiozlQqrvcoAGYzJ_w8,2852
-tasktree/parser.py,sha256=K83HyujCyh9NGJoBeUzozYRFQELNHPzWcJoZdPh79yE,56808
-tasktree/state.py,sha256=Cktl4D8iDZVd55aO2LqVyPrc-BnljkesxxkcMcdcfOY,3541
-tasktree/substitution.py,sha256=Sr8_aBdcWXtkCybkSFMHRjQyQSq-cMREtps_A9ASUgk,6320
-tasktree/tasks.py,sha256=2QdQZtJAX2rSGbyXKG1z9VF_siz1DUzdvzCgPkykxtU,173
-tasktree/types.py,sha256=R_YAyO5bMLB6XZnkMRT7VAtlkA_Xx6xu0aIpzQjrBXs,4357
-tasktree-0.0.8.dist-info/METADATA,sha256=JKjK-6i9ZlTq4gCVWl1dJE6W615tjtlQt64bPwi4vcU,34533
-tasktree-0.0.8.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-tasktree-0.0.8.dist-info/entry_points.txt,sha256=lQINlvRYnimvteBbnhH84A9clTg8NnpEjCWqWkqg8KE,40
-tasktree-0.0.8.dist-info/RECORD,,