tasktree 0.0.4__tar.gz → 0.0.6__tar.gz

{tasktree-0.0.4 → tasktree-0.0.6}/CLAUDE.md

@@ -58,12 +58,13 @@ The project uses Python's built-in `unittest` framework with mocking via `unitte
 
 Tasks are defined in YAML with the following structure:
 ```yaml
-task-name:
-  desc: Description (optional)
-  deps: [dependency-tasks]
-  inputs: [glob-patterns]
-  outputs: [glob-patterns]
-  working_dir: execution-directory
-  args: [typed-parameters]
-  cmd: shell-command
+tasks:
+  task-name:
+    desc: Description (optional)
+    deps: [dependency-tasks]
+    inputs: [glob-patterns]
+    outputs: [glob-patterns]
+    working_dir: execution-directory
+    args: [typed-parameters]
+    cmd: shell-command
 ```

{tasktree-0.0.4 → tasktree-0.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tasktree
-Version: 0.0.4
+Version: 0.0.6
 Summary: A task automation tool with incremental execution
 Requires-Python: >=3.11
 Requires-Dist: click>=8.1.0
@@ -70,33 +70,34 @@ Is this just whining and moaning? Should we just man up and revel in our own abi
 
 ... 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. 
+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
+tasks:
+  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:
@@ -107,6 +108,52 @@ Boom! Done. `build` will always run, because there's no sensible way to know wha
 
 This is a toy example, but you can image how it plays out on a more complex project.
 
+## Migrating from v1.x to v2.0
+
+Version 2.0 requires all task definitions to be under a top-level `tasks:` key.
+
+### Quick Migration
+
+Wrap your existing tasks in a `tasks:` block:
+
+```yaml
+# Before (v1.x)
+build:
+  cmd: cargo build
+
+# After (v2.0)
+tasks:
+  build:
+    cmd: cargo build
+```
+
+### Why This Change?
+
+1. **Clearer structure**: Explicit separation of tasks from configuration
+2. **No naming conflicts**: You can now create tasks named "imports" or "environments"
+3. **Better error messages**: More helpful validation errors
+4. **Consistency**: All recipe files use the same format
+
+### Error Messages
+
+If you forget to update, you'll see a clear error:
+
+```
+Invalid recipe format in tasktree.yaml
+
+Task definitions must be under a top-level "tasks:" key.
+
+Found these keys at root level: build, test
+
+Did you mean:
+
+tasks:
+  build:
+    cmd: ...
+  test:
+    cmd: ...
+```
+
 ## Installation
 
 ### From PyPI (Recommended)
@@ -141,20 +188,52 @@ cd tasktree
 pipx install .
 ```
 
+## Editor Support
+
+Task Tree includes a [JSON Schema](schema/tasktree-schema.json) that provides autocomplete, validation, and documentation in modern editors.
+
+### VS Code
+
+Install the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml), then add to your workspace `.vscode/settings.json`:
+
+```json
+{
+  "yaml.schemas": {
+    "https://raw.githubusercontent.com/kevinchannon/tasktree/main/schema/tasktree-schema.json": [
+      "tasktree.yaml",
+      "tt.yaml"
+    ]
+  }
+}
+```
+
+Or add a comment at the top of your `tasktree.yaml`:
+
+```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/kevinchannon/tasktree/main/schema/tasktree-schema.json
+
+tasks:
+  build:
+    cmd: cargo build
+```
+
+See [schema/README.md](schema/README.md) for IntelliJ/PyCharm and command-line validation.
+
 ## Quick Start
 
 Create a `tasktree.yaml` (or `tt.yaml`) in your project:
 
 ```yaml
-build:
-  desc: Compile the application
-  outputs: [target/release/bin]
-  cmd: cargo build --release
+tasks:
+  build:
+    desc: Compile the application
+    outputs: [target/release/bin]
+    cmd: cargo build --release
 
-test:
-  desc: Run tests
-  deps: [build]
-  cmd: cargo test
+  test:
+    desc: Run tests
+    deps: [build]
+    cmd: cargo test
 ```
 
 Run tasks:
@@ -185,15 +264,16 @@ Task Tree only runs tasks when necessary. A task executes if:
 Tasks automatically inherit inputs from dependencies, eliminating redundant declarations:
 
 ```yaml
-build:
-  outputs: [dist/app]
-  cmd: go build -o dist/app
-
-package:
-  deps: [build]
-  outputs: [dist/app.tar.gz]
-  cmd: tar czf dist/app.tar.gz dist/app
-  # Automatically tracks dist/app as an input
+tasks:
+  build:
+    outputs: [dist/app]
+    cmd: go build -o dist/app
+
+  package:
+    deps: [build]
+    outputs: [dist/app.tar.gz]
+    cmd: tar czf dist/app.tar.gz dist/app
+    # Automatically tracks dist/app as an input
 ```
 
 ### Single State File
@@ -205,15 +285,16 @@ All state lives in `.tasktree-state` at your project root. Stale entries are aut
 ### Basic Structure
 
 ```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)
-  env: bash-strict                       # Execution environment (optional)
-  args: [param1, param2:path=default]    # Task parameters
-  cmd: go build -o dist/binary           # Command to execute
+tasks:
+  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)
+    env: bash-strict                       # Execution environment (optional)
+    args: [param1, param2:path=default]    # Task parameters
+    cmd: go build -o dist/binary           # Command to execute
 ```
 
 ### Commands
@@ -221,18 +302,20 @@ task-name:
 **Single-line commands** are executed directly via the configured shell:
 
 ```yaml
-build:
-  cmd: cargo build --release
+tasks:
+  build:
+    cmd: cargo build --release
 ```
 
 **Multi-line commands** are written to temporary script files for proper execution:
 
 ```yaml
-deploy:
-  cmd: |
-    mkdir -p dist
-    cp build/* dist/
-    rsync -av dist/ server:/opt/app/
+tasks:
+  deploy:
+    cmd: |
+      mkdir -p dist
+      cp build/* dist/
+      rsync -av dist/ server:/opt/app/
 ```
 
 Multi-line commands preserve shell syntax (line continuations, heredocs, etc.) and support shebangs on Unix/macOS.
@@ -240,12 +323,13 @@ Multi-line commands preserve shell syntax (line continuations, heredocs, etc.) a
 Or use folded blocks for long single-line commands:
 
 ```yaml
-compile:
-  cmd: >
-    gcc -o bin/app
-    src/*.c
-    -I include
-    -L lib -lm
+tasks:
+  compile:
+    cmd: >
+      gcc -o bin/app
+      src/*.c
+      -I include
+      -L lib -lm
 ```
 
 ### Execution Environments
@@ -305,12 +389,13 @@ tasks:
 Tasks can accept arguments with optional defaults:
 
 ```yaml
-deploy:
-  args: [environment, region=eu-west-1]
-  deps: [build]
-  cmd: |
-    aws s3 cp dist/app.zip s3://{{environment}}-{{region}}/
-    aws lambda update-function-code --function-name app-{{environment}}
+tasks:
+  deploy:
+    args: [environment, region=eu-west-1]
+    deps: [build]
+    cmd: |
+      aws s3 cp dist/app.zip s3://{{environment}}-{{region}}/
+      aws lambda update-function-code --function-name app-{{environment}}
 ```
 
 Invoke with: `tt deploy production` or `tt deploy staging us-east-1` or `tt deploy staging region=us-east-1`. 
@@ -337,18 +422,19 @@ Split task definitions across multiple files for better organisation:
 
 ```yaml
 # tasktree.yaml
-import:
+imports:
   - file: build/tasks.yml
     as: build
   - file: deploy/tasks.yml
     as: deploy
 
-test:
-  deps: [build.compile, build.test-compile]
-  cmd: ./run-tests.sh
+tasks:
+  test:
+    deps: [build.compile, build.test-compile]
+    cmd: ./run-tests.sh
 
-ci:
-  deps: [build.all, test, deploy.staging]
+  ci:
+    deps: [build.all, test, deploy.staging]
 ```
 
 Imported tasks are namespaced and can be referenced as dependencies. Each imported file is self-contained—it cannot depend on tasks in the importing file.
@@ -466,41 +552,42 @@ imports:
   - file: common/docker.yml
     as: docker
 
-compile:
-  desc: Build application binaries
-  outputs: [target/release/app]
-  cmd: cargo build --release
-
-test-unit:
-  desc: Run unit tests
-  deps: [compile]
-  cmd: cargo test
-
-package:
-  desc: Create distribution archive
-  deps: [compile]
-  outputs: [dist/app-{{version}}.tar.gz]
-  args: [version]
-  cmd: |
-    mkdir -p dist
-    tar czf dist/app-{{version}}.tar.gz \
-      target/release/app \
-      config/ \
-      migrations/
-
-deploy:
-  desc: Deploy to environment
-  deps: [package, docker.build-runtime]
-  args: [environment, version]
-  cmd: |
-    scp dist/app-{{version}}.tar.gz {{environment}}:/opt/
-    ssh {{environment}} /opt/deploy.sh {{version}}
-
-integration-test:
-  desc: Run integration tests against deployed environment
-  deps: [deploy]
-  args: [environment, version]
-  cmd: pytest tests/integration/ --env={{environment}}
+tasks:
+  compile:
+    desc: Build application binaries
+    outputs: [target/release/app]
+    cmd: cargo build --release
+
+  test-unit:
+    desc: Run unit tests
+    deps: [compile]
+    cmd: cargo test
+
+  package:
+    desc: Create distribution archive
+    deps: [compile]
+    outputs: [dist/app-{{version}}.tar.gz]
+    args: [version]
+    cmd: |
+      mkdir -p dist
+      tar czf dist/app-{{version}}.tar.gz \
+        target/release/app \
+        config/ \
+        migrations/
+
+  deploy:
+    desc: Deploy to environment
+    deps: [package, docker.build-runtime]
+    args: [environment, version]
+    cmd: |
+      scp dist/app-{{version}}.tar.gz {{environment}}:/opt/
+      ssh {{environment}} /opt/deploy.sh {{version}}
+
+  integration-test:
+    desc: Run integration tests against deployed environment
+    deps: [deploy]
+    args: [environment, version]
+    cmd: pytest tests/integration/ --env={{environment}}
 ```
 
 Run the full pipeline: