tasktree 0.0.2__py3-none-any.whl → 0.0.4__py3-none-any.whl

tasktree/cli.py

@@ -1,8 +1,5 @@
-"""Command-line interface for Task Tree."""
-
 from __future__ import annotations
 
-import sys
 from pathlib import Path
 from typing import Any, List, Optional
 
@@ -89,7 +86,7 @@ def _show_task(task_name: str):
 
 
 def _show_tree(task_name: str):
-    """Show dependency tree with freshness indicators."""
+    """Show dependency tree structure."""
     recipe = _get_recipe()
     if recipe is None:
         console.print("[red]No recipe file found (tasktree.yaml or tt.yaml)[/red]")
@@ -107,59 +104,11 @@ def _show_tree(task_name: str):
         console.print(f"[red]Error building dependency tree: {e}[/red]")
         raise typer.Exit(1)
 
-    # Get execution statuses
-    state = StateManager(recipe.project_root)
-    state.load()
-    executor = Executor(recipe, state)
-    statuses = executor.execute_task(task_name, dry_run=True)
-
     # Build Rich tree
-    tree = _build_rich_tree(dep_tree, statuses)
+    tree = _build_rich_tree(dep_tree)
     console.print(tree)
 
 
-def _dry_run(task_name: str):
-    """Show what would be executed without actually running."""
-    recipe = _get_recipe()
-    if recipe is None:
-        console.print("[red]No recipe file found (tasktree.yaml or tt.yaml)[/red]")
-        raise typer.Exit(1)
-
-    task = recipe.get_task(task_name)
-    if task is None:
-        console.print(f"[red]Task not found: {task_name}[/red]")
-        raise typer.Exit(1)
-
-    # Get execution plan
-    state = StateManager(recipe.project_root)
-    state.load()
-    executor = Executor(recipe, state)
-    statuses = executor.execute_task(task_name, dry_run=True)
-
-    # Display plan
-    console.print(f"[bold]Execution plan for '{task_name}':[/bold]\n")
-
-    will_run = [name for name, status in statuses.items() if status.will_run]
-    will_skip = [name for name, status in statuses.items() if not status.will_run]
-
-    if will_run:
-        console.print(f"[yellow]Will execute ({len(will_run)} tasks):[/yellow]")
-        for i, name in enumerate(will_run, 1):
-            status = statuses[name]
-            console.print(f"  {i}. [cyan]{name}[/cyan]")
-            console.print(f"     - {status.reason}")
-            if status.changed_files:
-                console.print(f"     - changed files: {', '.join(status.changed_files)}")
-        console.print()
-
-    if will_skip:
-        console.print(f"[green]Will skip ({len(will_skip)} tasks):[/green]")
-        for name in will_skip:
-            status = statuses[name]
-            last_run_str = f", last run {status.last_run}" if status.last_run else ""
-            console.print(f"  - {name} (fresh{last_run_str})")
-
-
 def _init_recipe():
     """Create a blank recipe file with commented examples."""
     recipe_path = Path("tasktree.yaml")
@@ -168,7 +117,7 @@ def _init_recipe():
         raise typer.Exit(1)
 
     template = """# Task Tree Recipe
-# See https://github.com/kevinchannon/tasktree for documentation
+# See https://github.com/kevinchannon/task-tree for documentation
 
 # Example task definitions:
 
@@ -216,29 +165,30 @@ def main(
         is_eager=True,
         help="Show version and exit",
     ),
-    list_tasks: Optional[bool] = typer.Option(
-        None, "--list", "-l", help="List all available tasks"
-    ),
-    show: Optional[str] = typer.Option(None, "--show", help="Show task definition"),
-    tree: Optional[str] = typer.Option(None, "--tree", help="Show dependency tree"),
-    dry_run: Optional[str] = typer.Option(
-        None, "--dry-run", help="Show execution plan without running"
-    ),
+    list_opt: Optional[bool] = typer.Option(None, "--list", "-l", help="List all available tasks"),
+    show: Optional[str] = typer.Option(None, "--show", "-s", help="Show task definition"),
+    tree: Optional[str] = typer.Option(None, "--tree", "-t", help="Show dependency tree"),
     init: Optional[bool] = typer.Option(
-        None, "--init", help="Create a blank tasktree.yaml"
+        None, "--init", "-i", help="Create a blank tasktree.yaml"
     ),
     clean: Optional[bool] = typer.Option(
-        None, "--clean", help="Remove state file (reset task cache)"
+        None, "--clean", "-c", help="Remove state file (reset task cache)"
     ),
     clean_state: Optional[bool] = typer.Option(
-        None, "--clean-state", help="Remove state file (reset task cache)"
+        None, "--clean-state", "-C", help="Remove state file (reset task cache)"
     ),
     reset: Optional[bool] = typer.Option(
-        None, "--reset", help="Remove state file (reset task cache)"
+        None, "--reset", "-r", help="Remove state file (reset task cache)"
     ),
     force: Optional[bool] = typer.Option(
         None, "--force", "-f", help="Force re-run all tasks (ignore freshness)"
     ),
+    only: Optional[bool] = typer.Option(
+        None, "--only", "-o", help="Run only the specified task, skip dependencies (implies --force)"
+    ),
+    env: Optional[str] = typer.Option(
+        None, "--env", "-e", help="Override environment for all tasks"
+    ),
     task_args: Optional[List[str]] = typer.Argument(
         None, help="Task name and arguments"
     ),
@@ -255,41 +205,32 @@ def main(
       tt --list                    # List all tasks
       tt --tree test               # Show dependency tree for 'test'
     """
-    # Handle list option
-    if list_tasks:
+
+    if list_opt:
         _list_tasks()
         raise typer.Exit()
 
-    # Handle show option
     if show:
         _show_task(show)
         raise typer.Exit()
 
-    # Handle tree option
     if tree:
         _show_tree(tree)
         raise typer.Exit()
 
-    # Handle dry-run option
-    if dry_run:
-        _dry_run(dry_run)
-        raise typer.Exit()
-
-    # Handle init option
     if init:
         _init_recipe()
         raise typer.Exit()
 
-    # Handle clean options (all three aliases)
     if clean or clean_state or reset:
         _clean_state()
         raise typer.Exit()
 
-    # Handle task execution
     if task_args:
-        _execute_dynamic_task(task_args, force=force or False)
+        # --only implies --force
+        force_execution = force or only or False
+        _execute_dynamic_task(task_args, force=force_execution, only=only or False, env=env)
     else:
-        # No arguments - show available tasks
         recipe = _get_recipe()
         if recipe is None:
             console.print("[red]No recipe file found (tasktree.yaml or tt.yaml)[/red]")
@@ -322,7 +263,7 @@ def _clean_state() -> None:
         console.print(f"[yellow]No state file found at {state_path}[/yellow]")
 
 
-def _get_recipe() -> Recipe | None:
+def _get_recipe() -> Optional[Recipe]:
     """Get parsed recipe or None if not found."""
     recipe_path = find_recipe_file()
     if recipe_path is None:
@@ -335,13 +276,7 @@ def _get_recipe() -> Recipe | None:
         raise typer.Exit(1)
 
 
-def _execute_dynamic_task(args: list[str], force: bool = False) -> None:
-    """Execute a task specified by name with arguments.
-
-    Args:
-        args: Command line arguments (task name and task arguments)
-        force: If True, ignore freshness and re-run all tasks
-    """
+def _execute_dynamic_task(args: list[str], force: bool = False, only: bool = False, env: Optional[str] = None) -> None:
     if not args:
         return
 
@@ -353,6 +288,17 @@ def _execute_dynamic_task(args: list[str], force: bool = False) -> None:
         console.print("[red]No recipe file found (tasktree.yaml or tt.yaml)[/red]")
         raise typer.Exit(1)
 
+    # Apply global environment override if provided
+    if env:
+        # Validate that the environment exists
+        if not recipe.get_environment(env):
+            console.print(f"[red]Environment not found: {env}[/red]")
+            console.print("\nAvailable environments:")
+            for env_name in sorted(recipe.environments.keys()):
+                console.print(f"  - {env_name}")
+            raise typer.Exit(1)
+        recipe.global_env_override = env
+
     task = recipe.get_task(task_name)
     if task is None:
         console.print(f"[red]Task not found: {task_name}[/red]")
@@ -364,20 +310,20 @@ def _execute_dynamic_task(args: list[str], force: bool = False) -> None:
     # Parse task arguments
     args_dict = _parse_task_args(task.args, task_args)
 
-    # Prune state before execution
+    # Create executor and state manager
     state = StateManager(recipe.project_root)
     state.load()
+    executor = Executor(recipe, state)
+
+    # Prune state before execution (compute hashes with effective environment)
     valid_hashes = {
-        hash_task(t.cmd, t.outputs, t.working_dir, t.args)
+        hash_task(t.cmd, t.outputs, t.working_dir, t.args, executor._get_effective_env_name(t))
         for t in recipe.tasks.values()
     }
     state.prune(valid_hashes)
     state.save()
-
-    # Execute task
-    executor = Executor(recipe, state)
     try:
-        executor.execute_task(task_name, args_dict, dry_run=False, force=force)
+        executor.execute_task(task_name, args_dict, force=force, only=only)
         console.print(f"[green]✓ Task '{task_name}' completed successfully[/green]")
     except Exception as e:
         console.print(f"[red]✗ Task '{task_name}' failed: {e}[/red]")
@@ -385,31 +331,17 @@ def _execute_dynamic_task(args: list[str], force: bool = False) -> None:
 
 
 def _parse_task_args(arg_specs: list[str], arg_values: list[str]) -> dict[str, Any]:
-    """Parse command line arguments for a task.
-
-    Args:
-        arg_specs: Argument specifications from task definition
-        arg_values: Command line argument values
-
-    Returns:
-        Dictionary of argument names to values
-
-    Raises:
-        typer.Exit: If arguments are invalid
-    """
     if not arg_specs:
         if arg_values:
             console.print(f"[red]Task does not accept arguments[/red]")
             raise typer.Exit(1)
         return {}
 
-    # Parse argument specifications
     parsed_specs = []
     for spec in arg_specs:
         name, arg_type, default = parse_arg_spec(spec)
         parsed_specs.append((name, arg_type, default))
 
-    # Build argument dictionary
     args_dict = {}
     positional_index = 0
 
@@ -458,40 +390,13 @@ def _parse_task_args(arg_specs: list[str], arg_values: list[str]) -> dict[str, A
     return args_dict
 
 
-def _build_rich_tree(dep_tree: dict, statuses: dict) -> Tree:
-    """Build a Rich Tree from dependency tree and statuses.
-
-    Args:
-        dep_tree: Dependency tree structure
-        statuses: Task execution statuses
-
-    Returns:
-        Rich Tree for display
-    """
+def _build_rich_tree(dep_tree: dict) -> Tree:
     task_name = dep_tree["name"]
-    status = statuses.get(task_name)
-
-    # Determine color based on status
-    if status:
-        if status.will_run:
-            if status.reason == "dependency_triggered":
-                color = "yellow"
-                label = f"{task_name} (triggered by dependency)"
-            else:
-                color = "red"
-                label = f"{task_name} (stale: {status.reason})"
-        else:
-            color = "green"
-            label = f"{task_name} (fresh)"
-    else:
-        color = "white"
-        label = task_name
-
-    tree = Tree(f"[{color}]{label}[/{color}]")
+    tree = Tree(task_name)
 
     # Add dependencies
     for dep in dep_tree.get("deps", []):
-        dep_tree_obj = _build_rich_tree(dep, statuses)
+        dep_tree_obj = _build_rich_tree(dep)
         tree.add(dep_tree_obj)
 
     return tree

tasktree/executor.py

@@ -2,7 +2,11 @@
 
 from __future__ import annotations
 
+import os
+import platform
+import stat
 import subprocess
+import tempfile
 import time
 from dataclasses import dataclass, field
 from datetime import datetime
@@ -46,6 +50,85 @@ class Executor:
         self.recipe = recipe
         self.state = state_manager
 
+    def _get_platform_default_environment(self) -> 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 _get_effective_env_name(self, task: Task) -> str:
+        """Get the effective environment name for a task.
+
+        Resolution order:
+        1. Recipe's global_env_override (from CLI --env)
+        2. Task's explicit env field
+        3. Recipe's default_env
+        4. Empty string (for platform default)
+
+        Args:
+            task: Task to get environment name for
+
+        Returns:
+            Environment name (empty string if using platform default)
+        """
+        # Check for global override first
+        if self.recipe.global_env_override:
+            return self.recipe.global_env_override
+
+        # Use task's env
+        if task.env:
+            return task.env
+
+        # Use recipe default
+        if self.recipe.default_env:
+            return self.recipe.default_env
+
+        # Platform default (no env name)
+        return ""
+
+    def _resolve_environment(self, task: Task) -> tuple[str, list[str], str]:
+        """Resolve which environment to use for a task.
+
+        Resolution order:
+        1. Recipe's global_env_override (from CLI --env)
+        2. Task's explicit env field
+        3. Recipe's default_env
+        4. Platform default (bash on Unix, cmd on Windows)
+
+        Args:
+            task: Task to resolve environment for
+
+        Returns:
+            Tuple of (shell, args, preamble)
+        """
+        # Check for global override first
+        env_name = self.recipe.global_env_override
+
+        # If no global override, use task's env
+        if not env_name:
+            env_name = task.env
+
+        # If no explicit env, try recipe default
+        if not env_name and self.recipe.default_env:
+            env_name = self.recipe.default_env
+
+        # If we have an env name, look it up
+        if env_name:
+            env = self.recipe.get_environment(env_name)
+            if env:
+                return (env.shell, env.args, env.preamble)
+            # If env not found, fall through to platform default
+
+        # Use platform default
+        shell, args = self._get_platform_default_environment()
+        return (shell, args, "")
+
     def check_task_status(
         self,
         task: Task,
@@ -81,8 +164,9 @@ class Executor:
                 reason="forced",
             )
 
-        # Compute hashes
-        task_hash = hash_task(task.cmd, task.outputs, task.working_dir, task.args)
+        # Compute hashes (include effective environment)
+        effective_env = self._get_effective_env_name(task)
+        task_hash = hash_task(task.cmd, task.outputs, task.working_dir, task.args, effective_env)
         args_hash = hash_args(args_dict) if args_dict else None
         cache_key = make_cache_key(task_hash, args_hash)
 
@@ -146,16 +230,16 @@ class Executor:
         self,
         task_name: str,
         args_dict: dict[str, Any] | None = None,
-        dry_run: bool = False,
         force: bool = False,
+        only: bool = False,
     ) -> dict[str, TaskStatus]:
         """Execute a task and its dependencies.
 
         Args:
             task_name: Name of task to execute
             args_dict: Arguments to pass to the task
-            dry_run: If True, only check what would run without executing
             force: If True, ignore freshness and re-run all tasks
+            only: If True, run only the specified task without dependencies (implies force=True)
 
         Returns:
             Dictionary of task names to their execution status
@@ -166,8 +250,17 @@ class Executor:
         if args_dict is None:
             args_dict = {}
 
+        # When only=True, force execution (ignore freshness)
+        if only:
+            force = True
+
         # Resolve execution order
-        execution_order = resolve_execution_order(self.recipe, task_name)
+        if only:
+            # Only execute the target task, skip dependencies
+            execution_order = [task_name]
+        else:
+            # Execute task and all dependencies
+            execution_order = resolve_execution_order(self.recipe, task_name)
 
         # Check status of all tasks
         statuses: dict[str, TaskStatus] = {}
@@ -183,9 +276,6 @@ class Executor:
             status = self.check_task_status(task, task_args, dep_statuses, force=force)
             statuses[name] = status
 
-        if dry_run:
-            return statuses
-
         # Execute tasks that need to run
         for name in execution_order:
             status = statuses[name]
@@ -220,21 +310,116 @@ class Executor:
         # Determine working directory
         working_dir = self.recipe.project_root / task.working_dir
 
+        # Resolve environment for this task
+        shell, shell_args, preamble = self._resolve_environment(task)
+
         # Execute command
         print(f"Running: {task.name}")
+
+        # Detect multi-line commands (ignore trailing newlines from YAML folded blocks)
+        if "\n" in cmd.rstrip():
+            self._run_multiline_command(cmd, working_dir, task.name, shell, preamble)
+        else:
+            self._run_single_line_command(cmd, working_dir, task.name, shell, shell_args)
+
+        # Update state
+        self._update_state(task, args_dict)
+
+    def _run_single_line_command(
+        self, cmd: str, working_dir: Path, task_name: str, shell: str, shell_args: list[str]
+    ) -> None:
+        """Execute a single-line command via shell.
+
+        Args:
+            cmd: Command string
+            working_dir: Working directory
+            task_name: Task name (for error messages)
+            shell: Shell executable to use
+            shell_args: Arguments to pass to shell
+
+        Raises:
+            ExecutionError: If command execution fails
+        """
         try:
-            result = subprocess.run(
-                cmd,
-                shell=True,
+            # Build command: shell + args + cmd
+            full_cmd = [shell] + shell_args + [cmd]
+            subprocess.run(
+                full_cmd,
                 cwd=working_dir,
                 check=True,
                 capture_output=False,
             )
         except subprocess.CalledProcessError as e:
-            raise ExecutionError(f"Task '{task.name}' failed with exit code {e.returncode}")
+            raise ExecutionError(
+                f"Task '{task_name}' failed with exit code {e.returncode}"
+            )
 
-        # Update state
-        self._update_state(task, args_dict)
+    def _run_multiline_command(
+        self, cmd: str, working_dir: Path, task_name: str, shell: str, preamble: str
+    ) -> None:
+        """Execute a multi-line command via temporary script file.
+
+        Args:
+            cmd: Multi-line command string
+            working_dir: Working directory
+            task_name: Task name (for error messages)
+            shell: Shell to use for script execution
+            preamble: Preamble text to prepend to script
+
+        Raises:
+            ExecutionError: If command execution fails
+        """
+        # Determine file extension based on platform
+        is_windows = platform.system() == "Windows"
+        script_ext = ".bat" if is_windows else ".sh"
+
+        # Create temporary script file
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            suffix=script_ext,
+            delete=False,
+        ) as script_file:
+            script_path = script_file.name
+
+            # On Unix/macOS, add shebang if not present
+            if not is_windows and not cmd.startswith("#!"):
+                # Use the configured shell in shebang
+                shebang = f"#!/usr/bin/env {shell}\n"
+                script_file.write(shebang)
+
+            # Add preamble if provided
+            if preamble:
+                script_file.write(preamble)
+                if not preamble.endswith("\n"):
+                    script_file.write("\n")
+
+            # Write command to file
+            script_file.write(cmd)
+            script_file.flush()
+
+        try:
+            # Make executable on Unix/macOS
+            if not is_windows:
+                os.chmod(script_path, os.stat(script_path).st_mode | stat.S_IEXEC)
+
+            # Execute script file
+            try:
+                subprocess.run(
+                    [script_path],
+                    cwd=working_dir,
+                    check=True,
+                    capture_output=False,
+                )
+            except subprocess.CalledProcessError as e:
+                raise ExecutionError(
+                    f"Task '{task_name}' failed with exit code {e.returncode}"
+                )
+        finally:
+            # Clean up temporary file
+            try:
+                os.unlink(script_path)
+            except OSError:
+                pass  # Ignore cleanup errors
 
     def _substitute_args(self, cmd: str, args_dict: dict[str, Any]) -> str:
         """Substitute arguments in command string.
@@ -352,8 +537,9 @@ class Executor:
             task: Task that was executed
             args_dict: Arguments used for execution
         """
-        # Compute hashes
-        task_hash = hash_task(task.cmd, task.outputs, task.working_dir, task.args)
+        # Compute hashes (include effective environment)
+        effective_env = self._get_effective_env_name(task)
+        task_hash = hash_task(task.cmd, task.outputs, task.working_dir, task.args, effective_env)
         args_hash = hash_args(args_dict) if args_dict else None
         cache_key = make_cache_key(task_hash, args_hash)
 

tasktree/hasher.py

@@ -1,74 +1,27 @@
-"""Hashing logic for tasks and arguments."""
-
 import hashlib
 import json
-from typing import Any
-
-
-def hash_task(cmd: str, outputs: list[str], working_dir: str, args: list[str]) -> str:
-    """Compute task definition hash.
+from typing import Any, Optional
 
-    The hash includes:
-    - cmd: The command to execute
-    - outputs: Declared output files
-    - working_dir: Execution directory
-    - args: Parameter definitions (names and types)
 
-    The hash excludes:
-    - deps: Only affects scheduling order
-    - inputs: Tracked separately via timestamps
-    - desc: Documentation only
-
-    Args:
-        cmd: Command to execute
-        outputs: List of output glob patterns
-        working_dir: Working directory for execution
-        args: List of argument definitions
-
-    Returns:
-        8-character hex hash string
-    """
-    # Create a stable representation
+def hash_task(cmd: str, outputs: list[str], working_dir: str, args: list[str], env: str = "") -> str:
     data = {
         "cmd": cmd,
-        "outputs": sorted(outputs),  # Sort for stability
+        "outputs": sorted(outputs),
         "working_dir": working_dir,
-        "args": sorted(args),  # Sort for stability
+        "args": sorted(args),
+        "env": env,
     }
 
-    # Serialize to JSON with sorted keys for deterministic hashing
     serialized = json.dumps(data, sort_keys=True, separators=(",", ":"))
-
-    # Compute hash and truncate to 8 characters
     return hashlib.sha256(serialized.encode()).hexdigest()[:8]
 
 
 def hash_args(args_dict: dict[str, Any]) -> str:
-    """Compute hash of task arguments.
-
-    Args:
-        args_dict: Dictionary of argument names to values
-
-    Returns:
-        8-character hex hash string
-    """
-    # Serialize arguments to JSON with sorted keys for deterministic hashing
     serialized = json.dumps(args_dict, sort_keys=True, separators=(",", ":"))
-
-    # Compute hash and truncate to 8 characters
     return hashlib.sha256(serialized.encode()).hexdigest()[:8]
 
 
-def make_cache_key(task_hash: str, args_hash: str | None = None) -> str:
-    """Create cache key for task execution.
-
-    Args:
-        task_hash: Task definition hash
-        args_hash: Optional arguments hash
-
-    Returns:
-        Cache key string (task_hash or task_hash__args_hash)
-    """
+def make_cache_key(task_hash: str, args_hash: Optional[str] = None) -> str:
     if args_hash:
         return f"{task_hash}__{args_hash}"
     return task_hash

tasktree/parser.py

@@ -14,6 +14,21 @@ class CircularImportError(Exception):
     pass
 
 
+@dataclass
+class Environment:
+    """Represents an execution environment configuration."""
+
+    name: str
+    shell: str
+    args: list[str] = field(default_factory=list)
+    preamble: str = ""
+
+    def __post_init__(self):
+        """Ensure args is always a list."""
+        if isinstance(self.args, str):
+            self.args = [self.args]
+
+
 @dataclass
 class Task:
     """Represents a task definition."""
@@ -27,6 +42,7 @@ class Task:
     working_dir: str = ""
     args: list[str] = field(default_factory=list)
     source_file: str = ""  # Track which file defined this task
+    env: str = ""  # Environment name to use for execution
 
     def __post_init__(self):
         """Ensure lists are always lists."""
@@ -46,6 +62,9 @@ class Recipe:
 
     tasks: dict[str, Task]
     project_root: Path
+    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)
 
     def get_task(self, name: str) -> Task | None:
         """Get task by name.
@@ -62,6 +81,17 @@ class Recipe:
         """Get all task names."""
         return list(self.tasks.keys())
 
+    def get_environment(self, name: str) -> Environment | None:
+        """Get environment by name.
+
+        Args:
+            name: Environment name
+
+        Returns:
+            Environment if found, None otherwise
+        """
+        return self.environments.get(name)
+
 
 def find_recipe_file(start_dir: Path | None = None) -> Path | None:
     """Find recipe file (tasktree.yaml or tt.yaml) in current or parent directories.
@@ -94,6 +124,68 @@ def find_recipe_file(start_dir: Path | None = None) -> Path | None:
     return None
 
 
+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.
+
+    Args:
+        file_path: Path to YAML file
+        namespace: Optional namespace prefix for tasks
+        project_root: Root directory of the project
+        import_stack: Stack of files being imported (for circular detection)
+
+    Returns:
+        Tuple of (tasks, environments, default_env_name)
+    """
+    # Parse tasks normally
+    tasks = _parse_file(file_path, namespace, project_root, import_stack)
+
+    # Load YAML again to extract environments (only from root file)
+    environments: dict[str, Environment] = {}
+    default_env = ""
+
+    # Only parse environments from the root file (namespace is None)
+    if namespace is None:
+        with open(file_path, "r") as f:
+            data = yaml.safe_load(f)
+
+        if data and "environments" in data:
+            env_data = data["environments"]
+            if isinstance(env_data, dict):
+                # Extract default environment name
+                default_env = env_data.get("default", "")
+
+                # Parse each environment definition
+                for env_name, env_config in env_data.items():
+                    if env_name == "default":
+                        continue  # Skip the default key itself
+
+                    if not isinstance(env_config, dict):
+                        raise ValueError(
+                            f"Environment '{env_name}' must be a dictionary"
+                        )
+
+                    # Parse environment configuration
+                    shell = env_config.get("shell", "")
+                    if not shell:
+                        raise ValueError(
+                            f"Environment '{env_name}' must specify 'shell'"
+                        )
+
+                    args = env_config.get("args", [])
+                    preamble = env_config.get("preamble", "")
+
+                    environments[env_name] = Environment(
+                        name=env_name, shell=shell, args=args, preamble=preamble
+                    )
+
+    return tasks, environments, default_env
+
+
 def parse_recipe(recipe_path: Path) -> Recipe:
     """Parse a recipe file and handle imports recursively.
 
@@ -115,9 +207,16 @@ def parse_recipe(recipe_path: Path) -> Recipe:
     project_root = recipe_path.parent
 
     # Parse main file - it will recursively handle all imports
-    tasks = _parse_file(recipe_path, namespace=None, project_root=project_root)
+    tasks, environments, default_env = _parse_file_with_env(
+        recipe_path, namespace=None, project_root=project_root
+    )
 
-    return Recipe(tasks=tasks, project_root=project_root)
+    return Recipe(
+        tasks=tasks,
+        project_root=project_root,
+        environments=environments,
+        default_env=default_env,
+    )
 
 
 def _parse_file(
@@ -198,10 +297,14 @@ def _parse_file(
 
             tasks.update(nested_tasks)
 
+    # Determine where tasks are defined
+    # Tasks can be either at root level OR inside a "tasks:" key
+    tasks_data = data.get("tasks", data) if "tasks" in data else data
+
     # Process local tasks
-    for task_name, task_data in data.items():
-        # Skip import declarations
-        if task_name == "import":
+    for task_name, task_data in tasks_data.items():
+        # Skip special sections (only relevant if tasks are at root level)
+        if task_name in ("import", "environments", "tasks"):
             continue
 
         if not isinstance(task_data, dict):

tasktree/types.py

@@ -4,7 +4,7 @@ import re
 from datetime import datetime
 from ipaddress import IPv4Address, IPv6Address, ip_address
 from pathlib import Path
-from typing import Any
+from typing import Any, Optional
 
 import click
 
@@ -19,7 +19,7 @@ class HostnameType(click.ParamType):
         r"^(?=.{1,253}$)(?!-)[A-Za-z0-9-]{1,63}(?<!-)(\.[A-Za-z0-9-]{1,63})*\.?$"
     )
 
-    def convert(self, value: Any, param: click.Parameter | None, ctx: click.Context | None) -> str:
+    def convert(self, value: Any, param: Optional[click.Parameter], ctx: Optional[click.Context]) -> str:
         if isinstance(value, str):
             if self.HOSTNAME_PATTERN.match(value):
                 return value
@@ -36,7 +36,7 @@ class EmailType(click.ParamType):
         r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$"
     )
 
-    def convert(self, value: Any, param: click.Parameter | None, ctx: click.Context | None) -> str:
+    def convert(self, value: Any, param: Optional[click.Parameter], ctx: Optional[click.Context]) -> str:
         if isinstance(value, str):
             if self.EMAIL_PATTERN.match(value):
                 return value
@@ -48,7 +48,7 @@ class IPType(click.ParamType):
 
     name = "ip"
 
-    def convert(self, value: Any, param: click.Parameter | None, ctx: click.Context | None) -> str:
+    def convert(self, value: Any, param: Optional[click.Parameter], ctx: Optional[click.Context]) -> str:
         try:
             ip_address(value)
             return str(value)
@@ -61,7 +61,7 @@ class IPv4Type(click.ParamType):
 
     name = "ipv4"
 
-    def convert(self, value: Any, param: click.Parameter | None, ctx: click.Context | None) -> str:
+    def convert(self, value: Any, param: Optional[click.Parameter], ctx: Optional[click.Context]) -> str:
         try:
             IPv4Address(value)
             return str(value)
@@ -74,7 +74,7 @@ class IPv6Type(click.ParamType):
 
     name = "ipv6"
 
-    def convert(self, value: Any, param: click.Parameter | None, ctx: click.Context | None) -> str:
+    def convert(self, value: Any, param: Optional[click.Parameter], ctx: Optional[click.Context]) -> str:
         try:
             IPv6Address(value)
             return str(value)
@@ -87,7 +87,7 @@ class DateTimeType(click.ParamType):
 
     name = "datetime"
 
-    def convert(self, value: Any, param: click.Parameter | None, ctx: click.Context | None) -> str:
+    def convert(self, value: Any, param: Optional[click.Parameter], ctx: Optional[click.Context]) -> str:
         if isinstance(value, str):
             try:
                 datetime.fromisoformat(value)

{tasktree-0.0.2.dist-info → tasktree-0.0.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tasktree
-Version: 0.0.2
+Version: 0.0.4
 Summary: A task automation tool with incremental execution
 Requires-Python: >=3.11
 Requires-Dist: click>=8.1.0
@@ -18,6 +18,95 @@ Description-Content-Type: text/markdown
 
 A task automation tool that combines simple command execution with dependency tracking and incremental execution.
 
+## Motivation
+In any project of even moderate size, various scripts inevitably come into being along the way. These scripts often must be run in a particular order, or at a particular time. For historical reasons, this almost certainly a problem if your project is developed in a Linux environment; in Windows, an IDE like Visual Studio may be taking care of a significant proportion of your build, packaging and deployment tasks. Then again, it may not...
+
+The various incantations that have to be issued to build, package, test and deploy a project can build up and then all of a sudden there's only a few people that remember which to invoke and when and then people start making helpful readme guides on what to do with the scripts and then those become out of date and start telling lies about things and so on.
+
+Then there's the scripts themselves. In Linux, they're probably a big pile of Bash and Python, or something (Ruby, Perl, you name it). You can bet the house on people solving the problem of passing parameters to their scripts in a whole bunch of different and inconsistent ways.
+
+```bash
+#!/usr/bin/env bash
+# It's an environment variable defined.... somewhere?
+echo "FOO is: $FOO"
+```
+```bash
+#!/usr/bin/env bash
+# Using simple positional arguments... guess what means what when you're invoking it!
+echo "First: $1, Second: $2"
+```
+```bash
+#!/usr/bin/env bash
+# Oooooh fancy "make me look like a proper app" named option parsing... don't try and do --foo=bar though!
+FOO=""
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --foo) FOO=$2; shift ;;
+        --)    break ;;
+        *)     echo "Unknown: $1";;
+    esac
+    shift
+done
+```
+```bash
+#!/usr/bin/env bash
+# This thing...
+ARGS=$(getopt -o f:b --long foo:,bar: -n 'myscript' -- "$@")
+eval set -- "$ARGS"
+while true; do
+    case "$1" in
+        -b|--bar) echo "Bar: $2"; shift 2 ;;
+        -f|--foo) echo "Foo: $2"; shift 2 ;;
+        --) shift; break ;;
+        *) break ;;
+    esac
+done
+```
+
+What about help info? Who has time to wire that in?
+
+### The point
+Is this just whining and moaning? Should we just man up and revel in our own ability to memorize all the right incantations like some kind of scripting shaman?
+
+... No. That's **a dumb idea**.
+
+Task Tree allows you to pile all the knowledge of **what** to run, **when** to run it, **where** to run it and **how** to run it into a single, readable place. Then you can delete all the scripts that no-one knows how to use and all the readme docs that lie to the few people that actually waste their time reading them. 
+
+The tasks you need to perform to deliver your project become summarised in an executable file that looks like:
+```yaml
+build:
+  desc: Compile stuff
+  outputs: [target/release/bin]
+  cmd: cargo build --release
+
+package:
+   desc: build installers
+   deps: [build]
+   outputs: [awesome.deb]
+   cmd: |
+      for bin in target/release/*; do
+          if [[ -x "$bin" && ! -d "$bin" ]]; then
+              install -Dm755 "$bin" "debian/awesome/usr/bin/$(basename "$bin")"
+          fi
+      done
+      
+      dpkg-buildpackage -us -uc
+
+test:
+  desc: Run tests
+  deps: [package]
+  inputs: [tests/**/*.py]
+  cmd: PYTHONPATH=src python3 -m pytest tests/ -v
+```
+
+If you want to run the tests then:
+```bash
+tt test
+```
+Boom! Done. `build` will always run, because there's no sensible way to know what Cargo did. However, if Cargo decided that nothing needed to be done and didn't touch the binaries, then `package` will realize that and not do anything. Then `test` will just run with the new tests that you just wrote. If you then immediately run `test` again, then `test` will figure out that none of the dependencies did anything and that none of the test files have changed and then just _do nothing_ - as it should.
+
+This is a toy example, but you can image how it plays out on a more complex project.
+
 ## Installation
 
 ### From PyPI (Recommended)
@@ -26,6 +115,16 @@ A task automation tool that combines simple command execution with dependency tr
 pipx install tasktree
 ```
 
+If you have multiple Python interpreter versions installed, and the _default_ interpreter is a version <3.11, then you can use `pipx`'s `--python` option to specify an interpreter with a version >=3.11:
+
+```bash
+# If the target version is on the PATH
+pipx install --python python3.12 tasktree
+
+# With a path to an interpreter
+pipx install --python /path/to/python3.12 tasktree
+```
+
 ### From Source
 
 For the latest unreleased version from GitHub:
@@ -61,9 +160,11 @@ test:
 Run tasks:
 
 ```bash
-tt build          # Build the application
-tt test           # Run tests (builds first if needed)
+tt                # Print the help
+tt --help         # ...also print the help
 tt --list         # Show all available tasks
+tt build          # Build the application (assuming this is in your tasktree.yaml)
+tt test           # Run tests (builds first if needed)
 ```
 
 ## Core Concepts
@@ -72,11 +173,12 @@ tt --list         # Show all available tasks
 
 Task Tree only runs tasks when necessary. A task executes if:
 
-- Its definition (command, outputs, working directory) has changed
+- Its definition (command, outputs, working directory, environment) has changed
 - Any input files have changed since the last run
 - Any dependencies have re-run
 - It has never been executed before
 - It has no inputs or outputs (always runs)
+- The execution environment has changed (CLI override or environment config change)
 
 ### Automatic Input Inheritance
 
@@ -105,17 +207,25 @@ All state lives in `.tasktree-state` at your project root. Stale entries are aut
 ```yaml
 task-name:
   desc: Human-readable description (optional)
-  deps: [other-task]              # Task dependencies
-  inputs: [src/**/*.go]            # Explicit input files (glob patterns)
-  outputs: [dist/binary]           # Output files (glob patterns)
-  working_dir: subproject/         # Execution directory (default: project root)
-  args: [param1, param2:path=default]   # Task parameters
-  cmd: go build -o dist/binary     # Command to execute
+  deps: [other-task]                     # Task dependencies
+  inputs: [src/**/*.go]                  # Explicit input files (glob patterns)
+  outputs: [dist/binary]                 # Output files (glob patterns)
+  working_dir: subproject/               # Execution directory (default: project root)
+  env: bash-strict                       # Execution environment (optional)
+  args: [param1, param2:path=default]    # Task parameters
+  cmd: go build -o dist/binary           # Command to execute
 ```
 
 ### Commands
 
-Multi-line commands using YAML literal blocks:
+**Single-line commands** are executed directly via the configured shell:
+
+```yaml
+build:
+  cmd: cargo build --release
+```
+
+**Multi-line commands** are written to temporary script files for proper execution:
 
 ```yaml
 deploy:
@@ -125,7 +235,9 @@ deploy:
     rsync -av dist/ server:/opt/app/
 ```
 
-Or folded blocks for long single-line commands:
+Multi-line commands preserve shell syntax (line continuations, heredocs, etc.) and support shebangs on Unix/macOS.
+
+Or use folded blocks for long single-line commands:
 
 ```yaml
 compile:
@@ -136,6 +248,58 @@ compile:
     -L lib -lm
 ```
 
+### Execution Environments
+
+Configure custom shell environments for task execution:
+
+```yaml
+environments:
+  default: bash-strict
+
+  bash-strict:
+    shell: bash
+    args: ['-c']              # For single-line: bash -c "command"
+    preamble: |               # For multi-line: prepended to script
+      set -euo pipefail
+
+  python:
+    shell: python
+    args: ['-c']
+
+  powershell:
+    shell: powershell
+    args: ['-ExecutionPolicy', 'Bypass', '-Command']
+    preamble: |
+      $ErrorActionPreference = 'Stop'
+
+tasks:
+  build:
+    # Uses 'default' environment (bash-strict)
+    cmd: cargo build --release
+
+  analyze:
+    env: python
+    cmd: |
+      import sys
+      print(f"Analyzing with Python {sys.version}")
+      # ... analysis code ...
+
+  windows-task:
+    env: powershell
+    cmd: |
+      Compress-Archive -Path dist/* -DestinationPath package.zip
+```
+
+**Environment resolution priority:**
+1. CLI override: `tt --env python build`
+2. Task's `env` field
+3. Recipe's `default` environment
+4. Platform default (bash on Unix, cmd on Windows)
+
+**Platform defaults** when no environments are configured:
+- **Unix/macOS**: bash with `-c` args
+- **Windows**: cmd with `/c` args
+
 ### Parameterised Tasks
 
 Tasks can accept arguments with optional defaults:
@@ -202,12 +366,19 @@ Input and output patterns support standard glob syntax:
 
 ### How State Works
 
-Each task is identified by a hash of its definition (command, outputs, working directory). State tracks:
+Each task is identified by a hash of its definition. The hash includes:
+
+- Command to execute
+- Output patterns
+- Working directory
+- Argument definitions
+- Execution environment
 
+State tracks:
 - When the task last ran
 - Timestamps of input files at that time
 
-Tasks are re-run when their definition changes or inputs are newer than the last run.
+Tasks are re-run when their definition changes, inputs are newer than the last run, or the environment changes.
 
 ### What's Not In The Hash
 
@@ -222,6 +393,72 @@ Changes to these don't invalidate cached state:
 
 At the start of each invocation, state is checked for invalid task hashes and non-existent ones are automatically removed. Delete a task from your recipe file and its state disappears the next time you run `tt <cmd>`
 
+## Command-Line Options
+
+Task Tree provides several command-line options for controlling task execution:
+
+### Execution Control
+
+```bash
+# Force re-run (ignore freshness checks)
+tt --force build
+tt -f build
+
+# Run only the specified task, skip dependencies (implies --force)
+tt --only deploy
+tt -o deploy
+
+# Override environment for all tasks
+tt --env python analyze
+tt -e powershell build
+```
+
+### Information Commands
+
+```bash
+# List all available tasks
+tt --list
+tt -l
+
+# Show detailed task definition
+tt --show build
+
+# Show dependency tree (without execution)
+tt --tree deploy
+
+# Show version
+tt --version
+tt -v
+
+# Create a blank recipe file
+tt --init
+```
+
+### State Management
+
+```bash
+# Remove state file (reset task cache)
+tt --clean
+tt --clean-state
+tt --reset
+```
+
+### Common Workflows
+
+```bash
+# Fresh build of everything
+tt --force build
+
+# Run a task without rebuilding dependencies
+tt --only test
+
+# Test with a different shell/environment
+tt --env python test
+
+# Force rebuild and deploy
+tt --force deploy production
+```
+
 ## Example: Full Build Pipeline
 
 ```yaml

tasktree-0.0.4.dist-info/RECORD

@@ -0,0 +1,13 @@
+tasktree/__init__.py,sha256=MVmdvKb3JdqLlo0x2_TPGMfgFC0HsDnP79HAzGnFnjI,1081
+tasktree/cli.py,sha256=2Pm0pxWdG4RaQbVMijaMUIrm3v0b9J98CUsUp7cDFvI,13236
+tasktree/executor.py,sha256=_E37tShHuiOj0Mvx2GbS9y3GIozC3hpzAVhAjbvYJqg,18638
+tasktree/graph.py,sha256=9ngfg93y7EkOIN_lUQa0u-JhnwiMN1UdQQvIFw8RYCE,4181
+tasktree/hasher.py,sha256=puJey9wF_p37k_xqjhYr_6ICsbAfrTBWHec6MqKV4BU,814
+tasktree/parser.py,sha256=apLfN3_YVa7lQIy0rcHFwo931Pg-8mKG1044AQE6fLQ,12690
+tasktree/state.py,sha256=rxKtS3SbsPtAuraHbN807RGWfoYYkQ3pe8CxUstwo2k,3535
+tasktree/tasks.py,sha256=2QdQZtJAX2rSGbyXKG1z9VF_siz1DUzdvzCgPkykxtU,173
+tasktree/types.py,sha256=w--sKjRTc8mGYkU5eAduqV86SolDqOYspAPuVKIuSQQ,3797
+tasktree-0.0.4.dist-info/METADATA,sha256=dxJ5QiaRWhBbae-cK358ESQuwbjDg04ITWomlgrO9Lc,16312
+tasktree-0.0.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+tasktree-0.0.4.dist-info/entry_points.txt,sha256=lQINlvRYnimvteBbnhH84A9clTg8NnpEjCWqWkqg8KE,40
+tasktree-0.0.4.dist-info/RECORD,,

tasktree-0.0.2.dist-info/RECORD

@@ -1,13 +0,0 @@
-tasktree/__init__.py,sha256=MVmdvKb3JdqLlo0x2_TPGMfgFC0HsDnP79HAzGnFnjI,1081
-tasktree/cli.py,sha256=VZGB8FJ8glZLn_z2bjSLLbmGRfFZ5Zh4nc1cYDLjGck,15904
-tasktree/executor.py,sha256=ZM-qEsgvjfRz77GEZzxF29L3I2d8Uz5W1ev7Mox9Vnc,12287
-tasktree/graph.py,sha256=9ngfg93y7EkOIN_lUQa0u-JhnwiMN1UdQQvIFw8RYCE,4181
-tasktree/hasher.py,sha256=jvXBvIfFH9g6AOBHHd012v8nG5JOgVnHH35mIEtVkwc,2133
-tasktree/parser.py,sha256=F2LbB84NinvBQT8zLONxn036R9Rued2y4XB3WGZ8PLk,9150
-tasktree/state.py,sha256=rxKtS3SbsPtAuraHbN807RGWfoYYkQ3pe8CxUstwo2k,3535
-tasktree/tasks.py,sha256=2QdQZtJAX2rSGbyXKG1z9VF_siz1DUzdvzCgPkykxtU,173
-tasktree/types.py,sha256=wrBzO-Z2ebCTRjWyOWNvuCjqAq-74Zyb9E4FQ4beF38,3751
-tasktree-0.0.2.dist-info/METADATA,sha256=yUoIhImEiwFND5rcCwzVdHosfW6BMvwbvdQgqF8EjnE,9145
-tasktree-0.0.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-tasktree-0.0.2.dist-info/entry_points.txt,sha256=lQINlvRYnimvteBbnhH84A9clTg8NnpEjCWqWkqg8KE,40
-tasktree-0.0.2.dist-info/RECORD,,