tasktree 0.0.18__py3-none-any.whl → 0.0.20__py3-none-any.whl

{tasktree-0.0.18.dist-info → tasktree-0.0.20.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tasktree
-Version: 0.0.18
+Version: 0.0.20
 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,420 @@ 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
+
+### Self-References
+
+Tasks can reference their own named inputs and outputs using `{{ self.inputs.name }}` and `{{ self.outputs.name }}` templates. This eliminates repetition when paths contain variables or when tasks have multiple inputs/outputs.
+
+**Named Inputs and Outputs:**
+
+Just like dependency output references, inputs and outputs can have names:
+
+```yaml
+tasks:
+  process:
+    inputs:
+      - src: "data/input.json"      # Named input
+      - config: "config.yaml"        # Named input
+    outputs:
+      - result: "output/result.json" # Named output
+      - log: "output/process.log"    # Named output
+    cmd: |
+      process-tool \
+        --input {{ self.inputs.src }} \
+        --config {{ self.inputs.config }} \
+        --output {{ self.outputs.result }} \
+        --log {{ self.outputs.log }}
+```
+
+**Syntax:**
+
+- **Defining named inputs**: `inputs: [{ name: "path/to/file" }]`
+- **Defining named outputs**: `outputs: [{ name: "path/to/file" }]`
+- **Referencing inputs**: `{{ self.inputs.input_name }}`
+- **Referencing outputs**: `{{ self.outputs.output_name }}`
+- **Mixed format**: Can combine named and anonymous inputs/outputs in the same task
+
+**Why Use Self-References?**
+
+Self-references follow the DRY (Don't Repeat Yourself) principle:
+
+```yaml
+# Without self-references - repetitive
+tasks:
+  build:
+    inputs: [src/app-{{ var.version }}.c]
+    outputs: [build/app-{{ var.version }}.o]
+    cmd: gcc src/app-{{ var.version }}.c -o build/app-{{ var.version }}.o
+
+# With self-references - DRY
+tasks:
+  build:
+    inputs:
+      - source: src/app-{{ var.version }}.c
+    outputs:
+      - object: build/app-{{ var.version }}.o
+    cmd: gcc {{ self.inputs.source }} -o {{ self.outputs.object }}
+```
+
+**Working with Variables:**
+
+Self-references work seamlessly with variables:
+
+```yaml
+variables:
+  platform: linux
+  arch: x86_64
+
+tasks:
+  compile:
+    inputs:
+      - src: src/{{ var.platform }}/main.c
+      - header: include/{{ var.arch }}/defs.h
+    outputs:
+      - binary: build/{{ var.platform }}-{{ var.arch }}/app
+    cmd: |
+      gcc {{ self.inputs.src }} \
+        -include {{ self.inputs.header }} \
+        -o {{ self.outputs.binary }}
+```
+
+Variables are evaluated first, then self-references substitute the expanded paths.
+
+**Working with Arguments:**
+
+Self-references work with parameterized tasks:
+
+```yaml
+tasks:
+  deploy:
+    args: [environment]
+    inputs:
+      - config: configs/{{ arg.environment }}/app.yaml
+    outputs:
+      - deployed: deployed-{{ arg.environment }}.yaml
+    cmd: |
+      validate {{ self.inputs.config }}
+      deploy {{ self.inputs.config }} > {{ self.outputs.deployed }}
+```
+
+```bash
+tt deploy production  # Uses configs/production/app.yaml
+tt deploy staging     # Uses configs/staging/app.yaml
+```
+
+**Working with Dependency Outputs:**
+
+Self-references and dependency references can be used together:
+
+```yaml
+tasks:
+  build:
+    outputs:
+      - artifact: dist/app.js
+    cmd: webpack build
+
+  package:
+    deps: [build]
+    inputs:
+      - manifest: package.json
+    outputs:
+      - tarball: release.tar.gz
+    cmd: tar czf {{ self.outputs.tarball }} \
+           {{ self.inputs.manifest }} \
+           {{ dep.build.outputs.artifact }}
+```
+
+**Mixed Named and Anonymous:**
+
+Tasks can mix named and anonymous inputs/outputs:
+
+```yaml
+tasks:
+  build:
+    inputs:
+      - config: build.yaml  # Named - can reference
+      - src/**/*.c          # Anonymous - tracked but not referenceable
+    outputs:
+      - binary: bin/app     # Named - can reference
+      - bin/app.debug       # Anonymous - tracked but not referenceable
+    cmd: build-tool --config {{ self.inputs.config }} --output {{ self.outputs.binary }}
+```
+
+**Error Messages:**
+
+If you reference a non-existent input or output:
+
+```yaml
+tasks:
+  build:
+    inputs:
+      - src: input.txt
+    cmd: cat {{ self.inputs.missing }}  # Error!
+```
+
+You'll get a clear error before execution:
+
+```
+Task 'build' references input 'missing' but has no input named 'missing'.
+Available named inputs: src
+Hint: Define named inputs like: inputs: [{ missing: 'path/to/file' }]
+```
+
+Similarly, if you try to reference an anonymous input:
+
+```yaml
+tasks:
+  build:
+    inputs: [file.txt]  # Anonymous input
+    cmd: cat {{ self.inputs.src }}  # Error!
+```
+
+You'll get:
+
+```
+Task 'build' references input 'src' but has no input named 'src'.
+Available named inputs: (none - all inputs are anonymous)
+Hint: Define named inputs like: inputs: [{ src: 'file.txt' }]
+```
+
+**Key Behaviors:**
+
+- **Template resolution**: Self-references are resolved during dependency graph planning
+- **Substitution order**: Variables → Dependency outputs → Self-references → Arguments/Environment
+- **Fail-fast validation**: Errors are caught before execution begins
+- **Clear error messages**: Lists available names if reference doesn't exist
+- **Backward compatible**: Existing anonymous inputs/outputs work unchanged
+- **State tracking**: Works correctly with incremental execution and freshness checks
+
+**Limitations:**
+
+- **Anonymous not referenceable**: Only named inputs/outputs can be referenced
+- **Case sensitive**: `{{ self.inputs.Src }}` and `{{ self.inputs.src }}` are different
+- **Argument defaults**: Self-references in argument defaults are not supported (arguments are evaluated before self-references)
+
+**Use Cases:**
+
+- **Eliminate repetition**: Define complex paths once, use them multiple times
+- **Variable composition**: Combine variables with self-references for clean commands
+- **Multiple inputs/outputs**: Reference specific files when tasks have many
+- **Complex build pipelines**: Keep commands readable with named artifacts
+- **Glob patterns**: Use self-references with glob patterns for dynamic inputs
+
+**Example: Multi-Stage Build:**
+
+```yaml
+variables:
+  version: "2.1.0"
+  platform: "linux"
+
+tasks:
+  prepare:
+    outputs:
+      - builddir: build/{{ var.platform }}-{{ var.version }}
+    cmd: mkdir -p {{ self.outputs.builddir }}
+
+  compile:
+    deps: [prepare]
+    inputs:
+      - source: src/main.c
+      - headers: include/*.h
+    outputs:
+      - object: build/{{ var.platform }}-{{ var.version }}/main.o
+    cmd: |
+      gcc -c {{ self.inputs.source }} \
+        -I include \
+        -o {{ self.outputs.object }}
+
+  link:
+    deps: [compile]
+    outputs:
+      - executable: build/{{ var.platform }}-{{ var.version }}/app
+      - symbols: build/{{ var.platform }}-{{ var.version }}/app.sym
+    cmd: |
+      gcc build/{{ var.platform }}-{{ var.version }}/main.o \
+        -o {{ self.outputs.executable }}
+      objcopy --only-keep-debug {{ self.outputs.executable }} {{ self.outputs.symbols }}
+```
+
+
+### 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 +1443,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.20.dist-info/RECORD

@@ -0,0 +1,14 @@
+tasktree/__init__.py,sha256=m7fLsPUft99oB_XXr4dOu2yUWu74zVutkw1-3zGrG5Y,1227
+tasktree/cli.py,sha256=S5ypqQlvCxdAvlBfO8TJZhvMoc086wqgvmOm8220678,21220
+tasktree/docker.py,sha256=qvja8G63uAcC73YMVY739egda1_CcBtoqzm0qIJU_Q8,14443
+tasktree/executor.py,sha256=g4mHtoO3wVIxyqNALIdJOEwlEqRkSY0eY-6sl2jF-IA,46463
+tasktree/graph.py,sha256=T78JH0whP7VquEvtOVN-8ePyHNcseTQoEouijDrgmkw,22663
+tasktree/hasher.py,sha256=o7Akd_AgGkAsnv9biK0AcbhlcqUQ9ne5y_6r4zoFaw0,5493
+tasktree/parser.py,sha256=R0swEkKBPGeijLHxD1CbQjtoKVn2gRJadsZuyKj1sdM,97922
+tasktree/state.py,sha256=Cktl4D8iDZVd55aO2LqVyPrc-BnljkesxxkcMcdcfOY,3541
+tasktree/substitution.py,sha256=FhtFI0ciK9bQxPdORvpf1coa59XxizKiBiUwHJp0PtI,16811
+tasktree/types.py,sha256=R_YAyO5bMLB6XZnkMRT7VAtlkA_Xx6xu0aIpzQjrBXs,4357
+tasktree-0.0.20.dist-info/METADATA,sha256=C8cdZtyz-dgiVoN1H2hy7wQNAA-K784WYFfqlZEOXnA,50237
+tasktree-0.0.20.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+tasktree-0.0.20.dist-info/entry_points.txt,sha256=lQINlvRYnimvteBbnhH84A9clTg8NnpEjCWqWkqg8KE,40
+tasktree-0.0.20.dist-info/RECORD,,

tasktree-0.0.18.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=o2AQuk9xeM9JCtyMzDeM0uJBsbJEhzPDxsPg9GwmJt4,88940
-tasktree/state.py,sha256=Cktl4D8iDZVd55aO2LqVyPrc-BnljkesxxkcMcdcfOY,3541
-tasktree/substitution.py,sha256=qG7SyEHn1PAKteWA0AgA1dUNbJfwQTupCLRq9FvOBD0,10724
-tasktree/types.py,sha256=R_YAyO5bMLB6XZnkMRT7VAtlkA_Xx6xu0aIpzQjrBXs,4357
-tasktree-0.0.18.dist-info/METADATA,sha256=u70mwnKCeb3sQkn5_B4cf0AOc8mI-FhvdTUbW0hoB3A,37234
-tasktree-0.0.18.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-tasktree-0.0.18.dist-info/entry_points.txt,sha256=lQINlvRYnimvteBbnhH84A9clTg8NnpEjCWqWkqg8KE,40
-tasktree-0.0.18.dist-info/RECORD,,