tasktree 0.0.17__py3-none-any.whl → 0.0.19__py3-none-any.whl

tasktree/__init__.py

@@ -13,6 +13,7 @@ from tasktree.graph import (
     TaskNotFoundError,
     build_dependency_tree,
     get_implicit_inputs,
+    resolve_dependency_output_references,
     resolve_execution_order,
 )
 from tasktree.hasher import hash_args, hash_task, make_cache_key
@@ -28,6 +29,7 @@ __all__ = [
     "TaskNotFoundError",
     "build_dependency_tree",
     "get_implicit_inputs",
+    "resolve_dependency_output_references",
     "resolve_execution_order",
     "hash_args",
     "hash_task",

tasktree/cli.py

@@ -14,7 +14,7 @@ from rich.tree import Tree
 
 from tasktree import __version__
 from tasktree.executor import Executor
-from tasktree.graph import build_dependency_tree, resolve_execution_order
+from tasktree.graph import build_dependency_tree, resolve_execution_order, resolve_dependency_output_references
 from tasktree.hasher import hash_task, hash_args
 from tasktree.parser import Recipe, find_recipe_file, parse_arg_spec, parse_recipe
 from tasktree.state import StateManager
@@ -110,8 +110,13 @@ 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)
 
-    # 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
+    # Calculate maximum task name length for fixed-width column (only visible tasks)
+    visible_task_names = []
+    for name in recipe.task_names():
+        task = recipe.get_task(name)
+        if task and not task.private:
+            visible_task_names.append(name)
+    max_task_name_len = max(len(name) for name in visible_task_names) if visible_task_names else 0
 
     # Create borderless table with three columns
     table = Table(show_edge=False, show_header=False, box=None, padding=(0, 2))
@@ -127,6 +132,9 @@ def _list_tasks(tasks_file: Optional[str] = None):
 
     for task_name in sorted(recipe.task_names()):
         task = recipe.get_task(task_name)
+        # Skip private tasks in list output
+        if task and task.private:
+            continue
         desc = task.desc if task else ""
         args_formatted = _format_task_arguments(task.args) if task else ""
 
@@ -344,7 +352,9 @@ def main(
 
         console.print("[bold]Available tasks:[/bold]")
         for task_name in sorted(recipe.task_names()):
-            console.print(f"  - {task_name}")
+            task = recipe.get_task(task_name)
+            if task and not task.private:
+                console.print(f"  - {task_name}")
         console.print("\nUse [cyan]tt --list[/cyan] for detailed information")
         console.print("Use [cyan]tt <task-name>[/cyan] to run a task")
 
@@ -437,7 +447,9 @@ def _execute_dynamic_task(args: list[str], force: bool = False, only: bool = Fal
         console.print(f"[red]Task not found: {task_name}[/red]")
         console.print("\nAvailable tasks:")
         for name in sorted(recipe.task_names()):
-            console.print(f"  - {name}")
+            task = recipe.get_task(name)
+            if task and not task.private:
+                console.print(f"  - {name}")
         raise typer.Exit(1)
 
     # Parse task arguments
@@ -452,6 +464,10 @@ def _execute_dynamic_task(args: list[str], force: bool = False, only: bool = Fal
     # This is important for correct state pruning after template substitution
     execution_order = resolve_execution_order(recipe, task_name, args_dict)
 
+    # Resolve dependency output references in topological order
+    # This substitutes {{ dep.*.outputs.* }} templates before execution
+    resolve_dependency_output_references(recipe, execution_order)
+
     # Prune state based on tasks that will actually execute (with their specific arguments)
     # This ensures template-substituted dependencies are handled correctly
     valid_hashes = set()

tasktree/executor.py

@@ -14,7 +14,7 @@ from pathlib import Path
 from typing import Any
 
 from tasktree import docker as docker_module
-from tasktree.graph import get_implicit_inputs, resolve_execution_order
+from tasktree.graph import get_implicit_inputs, resolve_execution_order, resolve_dependency_output_references
 from tasktree.hasher import hash_args, hash_task, make_cache_key
 from tasktree.parser import Recipe, Task, Environment
 from tasktree.state import StateManager, TaskState
@@ -433,6 +433,10 @@ class Executor:
             # Execute task and all dependencies
             execution_order = resolve_execution_order(self.recipe, task_name, args_dict)
 
+        # Resolve dependency output references in topological order
+        # This substitutes {{ dep.*.outputs.* }} templates before execution
+        resolve_dependency_output_references(self.recipe, execution_order)
+
         # Single phase: Check and execute incrementally
         statuses: dict[str, TaskStatus] = {}
         for name, task_args in execution_order:
@@ -1042,6 +1046,25 @@ class Executor:
 
         return changed_files
 
+    def _expand_output_paths(self, task: Task) -> list[str]:
+        """Extract all output paths from task outputs (both named and anonymous).
+
+        Args:
+            task: Task with outputs to extract
+
+        Returns:
+            List of output path patterns (glob patterns as strings)
+        """
+        paths = []
+        for output in task.outputs:
+            if isinstance(output, str):
+                # Anonymous output: just the path string
+                paths.append(output)
+            elif isinstance(output, dict):
+                # Named output: extract the path value
+                paths.extend(output.values())
+        return paths
+
     def _check_outputs_missing(self, task: Task) -> list[str]:
         """Check if any declared outputs are missing.
 
@@ -1057,7 +1080,10 @@ class Executor:
         missing_patterns = []
         base_path = self.recipe.project_root / task.working_dir
 
-        for pattern in task.outputs:
+        # Expand outputs to paths (handles both named and anonymous)
+        output_paths = self._expand_output_paths(task)
+
+        for pattern in output_paths:
             # Check if pattern has any matches
             matches = list(base_path.glob(pattern))
             if not matches:

tasktree/graph.py

@@ -306,6 +306,114 @@ def resolve_execution_order(
         raise CycleError(f"Dependency cycle detected: {e}")
 
 
+def resolve_dependency_output_references(
+    recipe: Recipe,
+    ordered_tasks: list[tuple[str, dict[str, Any]]],
+) -> None:
+    """Resolve {{ dep.<task>.outputs.<name> }} references in topological order.
+
+    This function walks through tasks in dependency order (dependencies first) and
+    resolves any references to dependency outputs in task fields. Templates are
+    resolved in place, modifying the Task objects in the recipe.
+
+    Args:
+        recipe: Recipe containing task definitions
+        ordered_tasks: List of (task_name, args) tuples in topological order
+
+    Raises:
+        ValueError: If template references cannot be resolved (missing task,
+                   missing output, task not in dependencies, etc.)
+
+    Example:
+        Given tasks in topological order: [('build', {}), ('deploy', {})]
+        If deploy.cmd contains "{{ dep.build.outputs.bundle }}", it will be
+        resolved to the actual output path from the build task.
+    """
+    from tasktree.substitution import substitute_dependency_outputs
+
+    # Track which tasks have been resolved (for validation)
+    resolved_tasks = {}
+
+    for task_name, task_args in ordered_tasks:
+        task = recipe.tasks.get(task_name)
+        if task is None:
+            continue  # Skip if task doesn't exist (shouldn't happen)
+
+        # Get list of dependency task names for this task
+        dep_task_names = []
+        for dep_spec in task.deps:
+            # Handle both string and dict dependency specs
+            if isinstance(dep_spec, str):
+                dep_task_names.append(dep_spec)
+            elif isinstance(dep_spec, dict):
+                # Dict spec: {"task_name": [args]}
+                dep_task_names.append(list(dep_spec.keys())[0])
+
+        # Resolve output references in command
+        if task.cmd:
+            task.cmd = substitute_dependency_outputs(
+                task.cmd,
+                task_name,
+                dep_task_names,
+                resolved_tasks,
+            )
+
+        # Resolve output references in working_dir
+        if task.working_dir:
+            task.working_dir = substitute_dependency_outputs(
+                task.working_dir,
+                task_name,
+                dep_task_names,
+                resolved_tasks,
+            )
+
+        # Resolve output references in outputs
+        resolved_outputs = []
+        for output in task.outputs:
+            if isinstance(output, str):
+                resolved_outputs.append(
+                    substitute_dependency_outputs(
+                        output,
+                        task_name,
+                        dep_task_names,
+                        resolved_tasks,
+                    )
+                )
+            elif isinstance(output, dict):
+                # Named output: resolve the path value
+                resolved_dict = {}
+                for name, path in output.items():
+                    resolved_dict[name] = substitute_dependency_outputs(
+                        path,
+                        task_name,
+                        dep_task_names,
+                        resolved_tasks,
+                    )
+                resolved_outputs.append(resolved_dict)
+        task.outputs = resolved_outputs
+
+        # Rebuild output maps after resolution
+        task.__post_init__()
+
+        # Resolve output references in argument defaults
+        if task.args:
+            for arg_spec in task.args:
+                if isinstance(arg_spec, dict):
+                    # Get arg name and details
+                    for arg_name, arg_details in arg_spec.items():
+                        if isinstance(arg_details, dict) and "default" in arg_details:
+                            if isinstance(arg_details["default"], str):
+                                arg_details["default"] = substitute_dependency_outputs(
+                                    arg_details["default"],
+                                    task_name,
+                                    dep_task_names,
+                                    resolved_tasks,
+                                )
+
+        # Mark this task as resolved for future references
+        resolved_tasks[task_name] = task
+
+
 def get_implicit_inputs(recipe: Recipe, task: Task) -> list[str]:
     """Get implicit inputs for a task based on its dependencies.
 
@@ -336,7 +444,14 @@ def get_implicit_inputs(recipe: Recipe, task: Task) -> list[str]:
 
         # If dependency has outputs, inherit them
         if dep_task.outputs:
-            implicit_inputs.extend(dep_task.outputs)
+            # Extract paths from both named and anonymous outputs
+            for output in dep_task.outputs:
+                if isinstance(output, str):
+                    # Anonymous output: just the path
+                    implicit_inputs.append(output)
+                elif isinstance(output, dict):
+                    # Named output: extract path values
+                    implicit_inputs.extend(output.values())
         # If dependency has no outputs, inherit its inputs
         elif dep_task.inputs:
             implicit_inputs.extend(dep_task.inputs)

tasktree/hasher.py

@@ -37,9 +37,38 @@ def _normalize_choices_lists(args: list[str | dict[str, Any]]) ->  list[str | di
     return normalized_args
 
 
+def _serialize_outputs_for_hash(outputs: list[str | dict[str, str]]) -> list[str]:
+    """Serialize outputs to consistent list of strings for hashing.
+
+    Converts both named outputs (dicts) and anonymous outputs (strings)
+    into a consistent, sortable format.
+
+    Args:
+        outputs: List of output specifications (strings or dicts)
+
+    Returns:
+        List of serialized output strings in sorted order
+
+    Example:
+        >>> _serialize_outputs_for_hash(["file.txt", {"bundle": "app.js"}])
+        ['bundle:app.js', 'file.txt']
+    """
+    serialized = []
+    for output in outputs:
+        if isinstance(output, str):
+            # Anonymous output: just the path
+            serialized.append(output)
+        elif isinstance(output, dict):
+            # Named output: serialize as "name:path" for each entry
+            # Sort dict items for consistent ordering
+            for name, path in sorted(output.items()):
+                serialized.append(f"{name}:{path}")
+    return sorted(serialized)
+
+
 def hash_task(
     cmd: str,
-    outputs: list[str],
+    outputs: list[str | dict[str, str]],
     working_dir: str,
     args: list[str | dict[str, Any]],
     env: str = "",
@@ -49,7 +78,7 @@ def hash_task(
 
     Args:
         cmd: Task command
-        outputs: Task outputs
+        outputs: Task outputs (strings or named dicts)
         working_dir: Working directory
         args: Task argument specifications
         env: Environment name
@@ -60,7 +89,7 @@ def hash_task(
     """
     data = {
         "cmd": cmd,
-        "outputs": sorted(outputs),
+        "outputs": _serialize_outputs_for_hash(outputs),
         "working_dir": working_dir,
         "args": sorted(_normalize_choices_lists(args), key=_arg_sort_key),
         "env": env,

tasktree/parser.py

@@ -58,14 +58,19 @@ class Task:
     desc: str = ""
     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)
+    outputs: list[str | dict[str, str]] = field(default_factory=list)  # Can be strings or dicts with named outputs
     working_dir: str = ""
     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
+    private: bool = False  # If True, task is hidden from --list output
+
+    # Internal fields for efficient output lookup (built in __post_init__)
+    _output_map: dict[str, str] = field(init=False, default_factory=dict, repr=False)  # name → path mapping
+    _anonymous_outputs: list[str] = field(init=False, default_factory=list, repr=False)  # unnamed outputs
 
     def __post_init__(self):
-        """Ensure lists are always lists."""
+        """Ensure lists are always lists and build output maps."""
         if isinstance(self.deps, str):
             self.deps = [self.deps]
         if isinstance(self.inputs, str):
@@ -88,6 +93,45 @@ class Task:
                 f"Arguments must be defined as a list, not a dictionary."
             )
 
+        # Build output maps for efficient lookup
+        self._output_map = {}
+        self._anonymous_outputs = []
+
+        for idx, output in enumerate(self.outputs):
+            if isinstance(output, dict):
+                # Named output: validate and store
+                if len(output) != 1:
+                    raise ValueError(
+                        f"Task '{self.name}': Named output at index {idx} must have exactly one key-value pair, got {len(output)}: {output}"
+                    )
+
+                name, path = next(iter(output.items()))
+
+                if not isinstance(path, str):
+                    raise ValueError(
+                        f"Task '{self.name}': Named output '{name}' must have a string path, got {type(path).__name__}: {path}"
+                    )
+
+                if not re.match(r'^[a-zA-Z_][a-zA-Z0-9_]*$', name):
+                    raise ValueError(
+                        f"Task '{self.name}': Named output '{name}' must be a valid identifier "
+                        f"(letters, numbers, underscores, cannot start with number)"
+                    )
+
+                if name in self._output_map:
+                    raise ValueError(
+                        f"Task '{self.name}': Duplicate output name '{name}' at index {idx}"
+                    )
+
+                self._output_map[name] = path
+            elif isinstance(output, str):
+                # Anonymous output: just store
+                self._anonymous_outputs.append(output)
+            else:
+                raise ValueError(
+                    f"Task '{self.name}': Output at index {idx} must be a string or dict, got {type(output).__name__}: {output}"
+                )
+
 
 @dataclass
 class DependencySpec:
@@ -237,9 +281,11 @@ class Recipe:
                 # Root task not found - fall back to eager evaluation
                 # This allows the recipe to be parsed even with invalid task names
                 # so the CLI can provide its own error message
+                reachable_tasks = self.tasks.keys()
                 variables_to_eval = set(self.raw_variables.keys())
         else:
             # Eager path: evaluate all variables (for --list command)
+            reachable_tasks = self.tasks.keys()
             variables_to_eval = set(self.raw_variables.keys())
 
         # Evaluate the selected variables using helper function
@@ -256,14 +302,64 @@ class Recipe:
         # Substitute evaluated variables into all tasks
         from tasktree.substitution import substitute_variables
 
-        for task in self.tasks.values():
+        for task_name, task in self.tasks.items():
+            if task_name not in reachable_tasks:
+                continue
+
             task.cmd = substitute_variables(task.cmd, self.evaluated_variables)
             task.desc = substitute_variables(task.desc, self.evaluated_variables)
             task.working_dir = substitute_variables(task.working_dir, self.evaluated_variables)
             task.inputs = [substitute_variables(inp, self.evaluated_variables) for inp in task.inputs]
-            task.outputs = [substitute_variables(out, self.evaluated_variables) for out in task.outputs]
-            # Substitute in argument default values (in arg spec strings)
-            task.args = [substitute_variables(arg, self.evaluated_variables) for arg in task.args]
+
+            # Substitute variables in outputs (handle both string and dict outputs)
+            resolved_outputs = []
+            for out in task.outputs:
+                if isinstance(out, str):
+                    resolved_outputs.append(substitute_variables(out, self.evaluated_variables))
+                elif isinstance(out, dict):
+                    # Named output: substitute the path value
+                    resolved_dict = {}
+                    for name, path in out.items():
+                        resolved_dict[name] = substitute_variables(path, self.evaluated_variables)
+                    resolved_outputs.append(resolved_dict)
+                else:
+                    resolved_outputs.append(out)
+            task.outputs = resolved_outputs
+
+            # Rebuild output maps after variable substitution
+            task.__post_init__()
+
+            # Substitute in argument default values (handle both string and dict args)
+            resolved_args = []
+            for arg in task.args:
+                if isinstance(arg, str):
+                    resolved_args.append(substitute_variables(arg, self.evaluated_variables))
+                elif isinstance(arg, dict):
+                    # Dict arg: substitute in nested values (like default values)
+                    resolved_dict = {}
+                    for arg_name, arg_spec in arg.items():
+                        if isinstance(arg_spec, dict):
+                            # Substitute in the nested dict values (e.g., default, help, choices)
+                            resolved_spec = {}
+                            for key, value in arg_spec.items():
+                                if isinstance(value, str):
+                                    resolved_spec[key] = substitute_variables(value, self.evaluated_variables)
+                                elif isinstance(value, list):
+                                    # Handle lists like 'choices'
+                                    resolved_spec[key] = [
+                                        substitute_variables(v, self.evaluated_variables) if isinstance(v, str) else v
+                                        for v in value
+                                    ]
+                                else:
+                                    resolved_spec[key] = value
+                            resolved_dict[arg_name] = resolved_spec
+                        else:
+                            # Simple value
+                            resolved_dict[arg_name] = substitute_variables(arg_spec, self.evaluated_variables) if isinstance(arg_spec, str) else arg_spec
+                    resolved_args.append(resolved_dict)
+                else:
+                    resolved_args.append(arg)
+            task.args = resolved_args
 
         # Substitute evaluated variables into all environments
         for env in self.environments.values():
@@ -330,19 +426,15 @@ def find_recipe_file(start_dir: Path | None = None) -> Path | None:
     while True:
         candidates = []
 
-        # Check for exact filenames first
+        # Check for exact filenames first (these are preferred)
         for filename in ["tasktree.yaml", "tasktree.yml", "tt.yaml"]:
             recipe_path = current / filename
             if recipe_path.exists():
                 candidates.append(recipe_path)
 
-        # Check for *.tasks files
-        for tasks_file in current.glob("*.tasks"):
-            if tasks_file.is_file():
-                candidates.append(tasks_file)
-
+        # If we found standard recipe files, use the first one
         if len(candidates) > 1:
-            # Multiple recipe files found - ambiguous
+            # Multiple standard recipe files found - ambiguous
             filenames = [c.name for c in candidates]
             raise ValueError(
                 f"Multiple recipe files found in {current}:\n"
@@ -353,6 +445,25 @@ def find_recipe_file(start_dir: Path | None = None) -> Path | None:
         elif len(candidates) == 1:
             return candidates[0]
 
+        # Only check for *.tasks files if no standard recipe files found
+        # (*.tasks files are typically imports, not main recipes)
+        tasks_files = []
+        for tasks_file in current.glob("*.tasks"):
+            if tasks_file.is_file():
+                tasks_files.append(tasks_file)
+
+        if len(tasks_files) > 1:
+            # Multiple *.tasks files found - ambiguous
+            filenames = [t.name for t in tasks_files]
+            raise ValueError(
+                f"Multiple recipe files found in {current}:\n"
+                f"  {', '.join(filenames)}\n\n"
+                f"Please specify which file to use with --tasks (-T):\n"
+                f"  tt --tasks {filenames[0]} <task-name>"
+            )
+        elif len(tasks_files) == 1:
+            return tasks_files[0]
+
         # Move to parent directory
         parent = current.parent
         if parent == current:
@@ -1368,8 +1479,15 @@ def collect_reachable_variables(
         # Search in outputs
         if task.outputs:
             for output_pattern in task.outputs:
-                for match in var_pattern.finditer(output_pattern):
-                    variables.add(match.group(1))
+                if isinstance(output_pattern, str):
+                    for match in var_pattern.finditer(output_pattern):
+                        variables.add(match.group(1))
+                elif isinstance(output_pattern, dict):
+                    # Named output - check the path value
+                    for output_path in output_pattern.values():
+                        if isinstance(output_path, str):
+                            for match in var_pattern.finditer(output_path):
+                                variables.add(match.group(1))
 
         # Search in argument defaults
         if task.args:
@@ -1695,6 +1813,7 @@ def _parse_file(
             args=task_data.get("args", []),
             source_file=str(file_path),
             env=task_data.get("env", ""),
+            private=task_data.get("private", False),
         )
 
         # Check for case-sensitive argument collisions

tasktree/substitution.py

@@ -15,6 +15,12 @@ PLACEHOLDER_PATTERN = re.compile(
     r'\{\{\s*(var|arg|env|tt)\s*\.\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}'
 )
 
+# Pattern matches: {{ dep.task_name.outputs.output_name }} with optional whitespace
+# Groups: (1) task_name (can include dots for namespacing), (2) output_name (identifier)
+DEP_OUTPUT_PATTERN = re.compile(
+    r'\{\{\s*dep\s*\.\s*([a-zA-Z_][a-zA-Z0-9_.-]*)\s*\.\s*outputs\s*\.\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}'
+)
+
 
 def substitute_variables(text: str | dict[str, Any], variables: dict[str, str]) -> str | dict[str, Any]:
     """Substitute {{ var.name }} placeholders with variable values.
@@ -290,3 +296,79 @@ def substitute_all(text: str, variables: dict[str, str], args: dict[str, Any]) -
     text = substitute_arguments(text, args)
     text = substitute_environment(text)
     return text
+
+
+def substitute_dependency_outputs(
+    text: str,
+    current_task_name: str,
+    current_task_deps: list[str],
+    resolved_tasks: dict[str, Any],
+) -> str:
+    """Substitute {{ dep.<task>.outputs.<name> }} placeholders with dependency output paths.
+
+    This function resolves references to named outputs from dependency tasks.
+    It validates that:
+    - The referenced task exists in the resolved_tasks dict
+    - The current task lists the referenced task as a dependency
+    - The referenced output name exists in the dependency task
+
+    Args:
+        text: Text containing {{ dep.*.outputs.* }} placeholders
+        current_task_name: Name of task being resolved (for error messages)
+        current_task_deps: List of dependency task names for the current task
+        resolved_tasks: Dictionary mapping task names to Task objects (already resolved)
+
+    Returns:
+        Text with all {{ dep.*.outputs.* }} placeholders replaced with output paths
+
+    Raises:
+        ValueError: If referenced task doesn't exist, isn't a dependency,
+                   or doesn't have the named output
+
+    Example:
+        >>> # Assuming build task has output { bundle: "dist/app.js" }
+        >>> substitute_dependency_outputs(
+        ...     "Deploy {{ dep.build.outputs.bundle }}",
+        ...     "deploy",
+        ...     ["build"],
+        ...     {"build": build_task}
+        ... )
+        'Deploy dist/app.js'
+    """
+    def replacer(match: re.Match) -> str:
+        dep_task_name = match.group(1)
+        output_name = match.group(2)
+
+        # Check if dependency task exists in resolved tasks
+        if dep_task_name not in resolved_tasks:
+            raise ValueError(
+                f"Task '{current_task_name}' references output from unknown task '{dep_task_name}'.\n"
+                f"Check the task name in {{{{ dep.{dep_task_name}.outputs.{output_name} }}}}"
+            )
+
+        # Check if current task depends on referenced task
+        if dep_task_name not in current_task_deps:
+            raise ValueError(
+                f"Task '{current_task_name}' references output from '{dep_task_name}' "
+                f"but does not list it as a dependency.\n"
+                f"Add '{dep_task_name}' to the deps list:\n"
+                f"  deps: [{', '.join(current_task_deps + [dep_task_name])}]"
+            )
+
+        # Get the dependency task
+        dep_task = resolved_tasks[dep_task_name]
+
+        # Look up the named output
+        if output_name not in dep_task._output_map:
+            available = list(dep_task._output_map.keys())
+            available_msg = ", ".join(available) if available else "(none - all outputs are anonymous)"
+            raise ValueError(
+                f"Task '{current_task_name}' references output '{output_name}' "
+                f"from task '{dep_task_name}', but '{dep_task_name}' has no output named '{output_name}'.\n"
+                f"Available named outputs in '{dep_task_name}': {available_msg}\n"
+                f"Hint: Define named outputs like: outputs: [{{ {output_name}: 'path/to/file' }}]"
+            )
+
+        return dep_task._output_map[output_name]
+
+    return DEP_OUTPUT_PATTERN.sub(replacer, text)

{tasktree-0.0.17.dist-info → tasktree-0.0.19.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tasktree
-Version: 0.0.17
+Version: 0.0.19
 Summary: A task automation tool with incremental execution
 Requires-Python: >=3.11
 Requires-Dist: click>=8.1.0
@@ -248,6 +248,7 @@ tasks:
     outputs: [dist/binary]                 # Output files (glob patterns)
     working_dir: subproject/               # Execution directory (default: project root)
     env: bash-strict                       # Execution environment (optional)
+    private: false                         # Hide from --list output (default: false)
     args:                                   # Task parameters
       - param1                              # Simple argument
       - param2: { type: path, default: "." }  # With type and default
@@ -687,6 +688,185 @@ tasks:
     cmd: echo "All tests passed"
 ```
 
+### Dependency Output References
+
+Tasks can reference named outputs from their dependencies, enabling dynamic workflows where build artifacts, generated filenames, and other values are passed between tasks.
+
+**Named Outputs:**
+
+Tasks can define outputs with names for easy referencing:
+
+```yaml
+tasks:
+  build:
+    outputs:
+      - bundle: "dist/app.js"        # Named output
+      - sourcemap: "dist/app.js.map" # Named output
+    cmd: webpack build
+
+  deploy:
+    deps: [build]
+    cmd: |
+      echo "Deploying {{ dep.build.outputs.bundle }}"
+      scp {{ dep.build.outputs.bundle }} server:/var/www/
+      scp {{ dep.build.outputs.sourcemap }} server:/var/www/
+```
+
+**Syntax:**
+
+- **Defining named outputs**: `outputs: [{ name: "path/to/file" }]`
+- **Referencing outputs**: `{{ dep.task_name.outputs.output_name }}`
+- **Mixed format**: Can combine named and anonymous outputs in the same task
+
+**Examples:**
+
+```yaml
+tasks:
+  # Generate a config file
+  generate-config:
+    outputs:
+      - config: "build/config.json"
+    cmd: |
+      mkdir -p build
+      echo '{"version": "1.0.0"}' > build/config.json
+
+  # Compile using the generated config
+  compile:
+    deps: [generate-config]
+    outputs:
+      - binary: "build/app"
+      - symbols: "build/app.sym"
+    cmd: |
+      echo "Using config: {{ dep.generate-config.outputs.config }}"
+      gcc -o build/app src/*.c
+
+  # Package multiple dependency outputs
+  package:
+    deps: [compile]
+    outputs:
+      - archive: "dist/app.tar.gz"
+    cmd: |
+      mkdir -p dist
+      tar czf {{ dep.package.outputs.archive }} \
+        {{ dep.compile.outputs.binary }} \
+        {{ dep.compile.outputs.symbols }}
+```
+
+**Mixed Named and Anonymous Outputs:**
+
+Tasks can have both named and anonymous outputs:
+
+```yaml
+tasks:
+  build:
+    outputs:
+      - binary: "build/app"      # Named - can be referenced
+      - "build/app.debug"        # Anonymous - tracked but not referenceable
+      - manifest: "build/manifest.json"  # Named - can be referenced
+    cmd: make all
+```
+
+**Transitive References:**
+
+Output references work across multiple levels of dependencies:
+
+```yaml
+tasks:
+  base:
+    outputs:
+      - lib: "out/libbase.a"
+    cmd: gcc -c base.c -o out/libbase.a
+
+  middleware:
+    deps: [base]
+    outputs:
+      - lib: "out/libmiddleware.a"
+    cmd: |
+      # Reference the base library
+      gcc -c middleware.c {{ dep.base.outputs.lib }} -o out/libmiddleware.a
+
+  app:
+    deps: [middleware]
+    cmd: |
+      # Reference middleware, which transitively used base
+      gcc main.c {{ dep.middleware.outputs.lib }} -o app
+```
+
+**Key Behaviors:**
+
+- **Template resolution**: Output references are resolved during dependency graph planning (in topological order)
+- **Fail-fast validation**: Errors are caught before execution begins
+- **Clear error messages**: If an output name doesn't exist, you get a list of available named outputs
+- **Backward compatible**: Existing anonymous outputs (`outputs: ["file.txt"]`) work unchanged
+- **Automatic input tracking**: Named outputs are automatically tracked as implicit inputs for dependent tasks
+
+**Error Messages:**
+
+If you reference a non-existent output:
+
+```yaml
+tasks:
+  build:
+    outputs:
+      - bundle: "dist/app.js"
+    cmd: webpack build
+
+  deploy:
+    deps: [build]
+    cmd: echo "{{ dep.build.outputs.missing }}"  # Error!
+```
+
+You'll get a clear error before execution:
+
+```
+Task 'deploy' references output 'missing' from task 'build',
+but 'build' has no output named 'missing'.
+Available named outputs in 'build': bundle
+Hint: Define named outputs like: outputs: [{ missing: 'path/to/file' }]
+```
+
+**Use Cases:**
+
+- **Dynamic artifact names**: Pass generated filenames between tasks
+- **Build metadata**: Reference manifests, checksums, or version files
+- **Multi-stage builds**: Chain compilation steps with specific output references
+- **Deployment pipelines**: Reference exact artifacts to deploy
+- **Configuration propagation**: Pass generated config files through build stages
+
+
+### Private Tasks
+
+Sometimes you may want to define helper tasks that are useful as dependencies but shouldn't be listed when users run `tt --list`. Mark these tasks as private:
+
+```yaml
+tasks:
+  # Private helper task - hidden from --list
+  setup-deps:
+    private: true
+    cmd: |
+      npm install
+      pip install -r requirements.txt
+
+  # Public task that uses the helper
+  build:
+    deps: [setup-deps]
+    cmd: npm run build
+```
+
+**Behavior:**
+- `tt --list` shows only public tasks (`build` in this example)
+- Private tasks can still be executed: `tt setup-deps` works
+- Private tasks work normally as dependencies
+- By default, all tasks are public (`private: false`)
+
+**Use cases:**
+- Internal helper tasks that shouldn't be run directly
+- Implementation details you want to hide from users
+- Shared setup tasks across multiple public tasks
+
+Note that private tasks remain fully functional - they're only hidden from the list view. Users who know the task name can still execute it directly.
+
+
 ## Environment Variables
 
 Task Tree supports reading environment variables in two ways:
@@ -1028,6 +1208,42 @@ At the start of each invocation, state is checked for invalid task hashes and no
 
 Task Tree provides several command-line options for controlling task execution:
 
+### Recipe File Selection
+
+Task Tree automatically discovers recipe files in the current directory and parent directories. You can also explicitly specify which file to use.
+
+**Automatic Discovery:**
+
+Task Tree searches for recipe files in the following order of preference:
+
+1. **Standard recipe files** (searched first, in order):
+   - `tasktree.yaml`
+   - `tasktree.yml`
+   - `tt.yaml`
+
+2. **Import files** (searched only if no standard files found):
+   - `*.tasks` files (e.g., `build.tasks`, `deploy.tasks`)
+
+If multiple files of the same priority level exist in the same directory, Task Tree will report an error and ask you to specify which file to use with `--tasks`.
+
+**Manual Selection:**
+
+```bash
+# Specify a recipe file explicitly
+tt --tasks build.tasks build
+tt -T custom-recipe.yaml test
+
+# Useful when you have multiple recipe files in the same directory
+tt --tasks ci.yaml deploy
+```
+
+**File Search Behavior:**
+
+- Task Tree searches **upward** from the current directory to find recipe files
+- **Standard recipe files** (`.yaml`/`.yml`) are always preferred over `*.tasks` files
+- `*.tasks` files are typically used for imports and are only used as main recipes if no standard files exist
+- The `.tasktree-state` file is created in the directory containing the recipe file
+
 ### Execution Control
 
 ```bash

tasktree-0.0.19.dist-info/RECORD

@@ -0,0 +1,14 @@
+tasktree/__init__.py,sha256=N-dZcggJDe4WaloC1MdEh0oMTHlUpBN9AEcAm6leDf4,1167
+tasktree/cli.py,sha256=_GzqQIk2z2Hz17bkTOWhtNW4X4_Ijxn-uEL-WZGt8LM,20858
+tasktree/docker.py,sha256=qvja8G63uAcC73YMVY739egda1_CcBtoqzm0qIJU_Q8,14443
+tasktree/executor.py,sha256=7pzcH2wLWMZPk3hwhzWgz18RVkIPFCKdu23MboWUQs4,45914
+tasktree/graph.py,sha256=9O5LByzMYa8ccedznqKBTb0Xe9N_aajSR1cAcb8zGQE,20366
+tasktree/hasher.py,sha256=o7Akd_AgGkAsnv9biK0AcbhlcqUQ9ne5y_6r4zoFaw0,5493
+tasktree/parser.py,sha256=PVgtGORCpnkb8wcXHFfsyVqDhJ3PwzwCqO3VWiuLQl4,94777
+tasktree/state.py,sha256=Cktl4D8iDZVd55aO2LqVyPrc-BnljkesxxkcMcdcfOY,3541
+tasktree/substitution.py,sha256=3-gdvHbBwPkQPflx3GVSpEEa0vTL_ivdcMIba77gtJc,14225
+tasktree/types.py,sha256=R_YAyO5bMLB6XZnkMRT7VAtlkA_Xx6xu0aIpzQjrBXs,4357
+tasktree-0.0.19.dist-info/METADATA,sha256=KTLp0p1Mkzzvah-Hy15KrXnTcKju5dlQyvDvEdnDOmg,43609
+tasktree-0.0.19.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+tasktree-0.0.19.dist-info/entry_points.txt,sha256=lQINlvRYnimvteBbnhH84A9clTg8NnpEjCWqWkqg8KE,40
+tasktree-0.0.19.dist-info/RECORD,,

tasktree-0.0.17.dist-info/RECORD

@@ -1,14 +0,0 @@
-tasktree/__init__.py,sha256=MVmdvKb3JdqLlo0x2_TPGMfgFC0HsDnP79HAzGnFnjI,1081
-tasktree/cli.py,sha256=Uhv0RNFrogjvqxBYKYIfxEPd0SdYAIpXH7SPGIxQnmk,20136
-tasktree/docker.py,sha256=qvja8G63uAcC73YMVY739egda1_CcBtoqzm0qIJU_Q8,14443
-tasktree/executor.py,sha256=QQcABThmof0MLTtwpJKpyqh80hr3YRIqqs3NZ-Ry-Bk,44873
-tasktree/graph.py,sha256=yITp71RfhJ7sdC-2zRf89SHYZqQyF3XVAnaqX-XnMdE,15821
-tasktree/hasher.py,sha256=0GrnCfwAXnwq_kpnHFFb12B5_2VFNXx6Ng7hTdcCyXo,4415
-tasktree/parser.py,sha256=5c3I2AUDJInGs6KLEIrxXOHnFo5_Ey4VbrzparUloQs,88755
-tasktree/state.py,sha256=Cktl4D8iDZVd55aO2LqVyPrc-BnljkesxxkcMcdcfOY,3541
-tasktree/substitution.py,sha256=qG7SyEHn1PAKteWA0AgA1dUNbJfwQTupCLRq9FvOBD0,10724
-tasktree/types.py,sha256=R_YAyO5bMLB6XZnkMRT7VAtlkA_Xx6xu0aIpzQjrBXs,4357
-tasktree-0.0.17.dist-info/METADATA,sha256=jtZiWlJCrszYT4FluXb7VTcZY_WEhtclu3Iqzglov9c,37234
-tasktree-0.0.17.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-tasktree-0.0.17.dist-info/entry_points.txt,sha256=lQINlvRYnimvteBbnhH84A9clTg8NnpEjCWqWkqg8KE,40
-tasktree-0.0.17.dist-info/RECORD,,