feat(tasks): add `usage` args to Tera context in run scripts #7041

iamkroot · 2025-11-22T06:05:29Z

We inject a usage map into the Tera context so that the args/flags can be accessed like {{usage.foo}}.

The map is also injected during (deprecated) spec-parsing so that this phase essentially becomes a no-op.

Related to #6766

Note

Expose parsed task args/flags as a usage map in Tera run scripts (including defaults during spec parsing), plus docs and tests.

Tasks/Parser:
- Inject usage map into Tera context for run scripts using parsed args/flags (parse_run_scripts_with_args).
- During spec-only and initial parsing, build and insert default usage map from usage::Spec to allow {{ usage.* }} without errors.
- Add helpers: make_usage_ctx (snake_case keys, booleans/strings/arrays) and make_usage_ctx_from_spec_defaults (handles var/count/boolean defaults).
Tests:
- Add e2e/tasks/test_task_usage_map_tera covering basic flags, variadic args arrays, and hyphenated names -> snake_case.
- Add unit tests for usage map exposure and MultiString handling in task_script_parser.rs.
Docs:
- Update docs/tasks/task-arguments.md and docs/templates.md to document the usage map in Tera scripts, key naming (snake_case or bracket access), value types, and examples.

^{Written by Cursor Bugbot for commit 80cb98f. This will update automatically on new commits. Configure here.}

Copilot

Pull request overview

This PR introduces a new experimental setting task.disable_spec_from_run_scripts that allows users to opt out of parsing task run scripts for usage specifications. When enabled, the usage spec will be derived solely from the usage field, bypassing template processing of arg(), option(), or flag() calls in run scripts. This restores previous behavior and improves performance by avoiding unnecessary template rendering.

Key Changes:

Added conditional logic in TaskScriptParser to skip spec collection from run scripts when the setting is enabled
Introduced a new make_usage_ctx helper to populate template context with parsed usage values
Added comprehensive tests to verify the new setting and usage context functionality

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
src/task/task_script_parser.rs	Modified spec collection methods to check the new setting and conditionally skip template-based spec parsing; added helper function for usage context creation and tests
settings.toml	Added configuration entry for the new `disable_spec_from_run_scripts` experimental option

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/task/task_script_parser.rs

docs/tasks/task-arguments.md

settings.toml

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/task/task_script_parser.rs

docs/templates.md

iamkroot · 2025-11-30T18:49:00Z

Should be ready to merge

jdx · 2025-12-01T11:22:59Z

bugbot run

src/task/task_script_parser.rs

jdx · 2025-12-01T11:39:53Z

this needs e2e tests

…ipts Introduced a new setting `task.disable_spec_from_run_scripts` in `settings.toml` to allow users to opt out of parsing task run scripts for usage specifications. When enabled, the usage spec will be derived solely from the `usage` field, ignoring any `arg()`, `option()`, or `flag()` templates in run scripts. This change aims to restore previous behavior and improve performance by avoiding unnecessary template processing. Updated the `TaskScriptParser` to respect this new setting during spec collection, ensuring that the behavior aligns with user preferences. Added tests to verify the functionality of the new option. Related to jdx#6766

jdx · 2025-12-02T03:46:51Z

bugbot run

cursor · 2025-12-02T03:54:43Z

src/task/task_script_parser.rs

+            let name = flag.name.to_snake_case();
+            let value = if flag.var {
+                // Option-like flags with values
+                tera::Value::String(flag.default.clone().unwrap_or_default())


Bug: Variadic value flags get inconsistent types during parsing

The make_usage_ctx_from_spec_defaults function creates a String for variadic flags (flag.var = true), rather than an Array. This is inconsistent with how variadic arguments are handled and with make_usage_ctx. As a result, templates expecting an array for these flags will encounter type mismatches during spec parsing.

@jdx This has revealed a bug/underspecification in usage.
I am punting it for now for the sake of getting this merged. Further discussion in jdx/usage#387

No point in testing wrong behavior

See jdx#7041

@RobotSupervisor

### 🚀 Features - **(config)** add support for netrc by @RobotSupervisor in [#7164](#7164) - **(lock)** add resolve_lock_info to core backends for checksum fetching by @jdx in [#7180](#7180) - **(ruby)** Install ruby from a zip file over HTTPS by @KaanYT in [#7167](#7167) - **(tasks)** add `usage` args to Tera context in run scripts by @iamkroot in [#7041](#7041) ### 🐛 Bug Fixes - **(lock)** validate platform qualifiers when reading from lockfile by @jdx in [#7181](#7181) - **(task)** retry shebang scripts on ETXTBUSY by @iamkroot in [#7162](#7162) - **(ui)** remove duplicate 'mise' prefix in verbose footer output by @jdx in [#7174](#7174) ### 📦️ Dependency Updates - bump usage-lib to 2.9.0 by @jdx in [#7177](#7177) ### 📦 Registry - remove duplicated ubi and github backends from gping by @risu729 in [#7144](#7144) - disable bashly test (not working in CI) by @jdx in [#7173](#7173) - disable cfn-lint test (failing in CI) by @jdx in [#7176](#7176) ### Chore - add fd to mise.toml by @blampe in [#7178](#7178) ### New Contributors - @RobotSupervisor made their first contribution in [#7164](#7164) ## 📦 Aqua Registry Updates #### New Packages (2) - [`Kitware/CMake`](https://github.com/Kitware/CMake) - [`quarto-dev/quarto-cli`](https://github.com/quarto-dev/quarto-cli) #### Updated Packages (6) - [`apache/jena`](https://github.com/apache/jena) - [`apache/spark`](https://github.com/apache/spark) - [`danielfoehrKn/kubeswitch`](https://github.com/danielfoehrKn/kubeswitch) - [`danielfoehrKn/kubeswitch/switch-sh`](https://github.com/danielfoehrKn/kubeswitch/switch-sh) - [`evilmartians/lefthook`](https://github.com/evilmartians/lefthook) - [`updatecli/updatecli`](https://github.com/updatecli/updatecli)

Copilot AI review requested due to automatic review settings November 22, 2025 06:05

Copilot AI reviewed Nov 22, 2025

View reviewed changes

src/task/task_script_parser.rs Outdated Show resolved Hide resolved

src/task/task_script_parser.rs Outdated Show resolved Hide resolved

jdx reviewed Nov 22, 2025

View reviewed changes

src/task/task_script_parser.rs Outdated Show resolved Hide resolved

iamkroot force-pushed the tera-usage branch from d83c331 to 20f8b34 Compare November 22, 2025 16:06

iamkroot mentioned this pull request Nov 22, 2025

feat(tasks): Forward usage multistring into a tera array #6728

Closed

jdx reviewed Nov 24, 2025

View reviewed changes

docs/tasks/task-arguments.md Outdated Show resolved Hide resolved

jdx reviewed Nov 24, 2025

View reviewed changes

settings.toml Outdated Show resolved Hide resolved

iamkroot force-pushed the tera-usage branch from 3e41032 to e8e1f84 Compare November 30, 2025 18:07

iamkroot changed the title ~~feat: add experimental option to disable spec collection from run scripts~~ feat: add usage to tera context in run scripts Nov 30, 2025

iamkroot force-pushed the tera-usage branch from 9b93044 to a523418 Compare November 30, 2025 18:38

iamkroot requested review from Copilot and jdx November 30, 2025 18:40

Copilot AI reviewed Nov 30, 2025

View reviewed changes

src/task/task_script_parser.rs Show resolved Hide resolved

src/task/task_script_parser.rs Show resolved Hide resolved

docs/templates.md Show resolved Hide resolved

iamkroot force-pushed the tera-usage branch from a27d0df to a523418 Compare November 30, 2025 18:46

cursor bot reviewed Dec 1, 2025

View reviewed changes

src/task/task_script_parser.rs Show resolved Hide resolved

Krut Patel and others added 12 commits December 1, 2025 22:47

[autofix.ci] apply automated fixes

e2d3e13

Add multistring test

e49296a

Fix test

62e81b6

Code cleanup

59ca10e

Fix tests

4935eb5

[autofix.ci] apply automated fixes

59ba26e

Always inject usage map into run script

866ed1d

Add docs

adb513d

Update docs

73bc3ba

[autofix.ci] apply automated fixes

26c26bd

Don't mark the setting as experimental

cc06b2c

Krut Patel and others added 7 commits December 1, 2025 22:47

fix(task): make usage ctx keys snake_case

ff1d977

Update docs

ce6ded1

Remove disable_spec_from_run_scripts

c949a5b

Fix outdated schema

bfd0650

[autofix.ci] apply automated fixes

b861c6d

Fix usage in run scripts

a46a995

Add e2e

eb764a6

iamkroot force-pushed the tera-usage branch from 1daa733 to eb764a6 Compare December 2, 2025 01:33

[autofix.ci] apply automated fixes

80cb98f

iamkroot changed the title ~~feat: add usage to tera context in run scripts~~ feat(tasks): add usage to tera context in run scripts Dec 2, 2025

iamkroot changed the title ~~feat(tasks): add usage to tera context in run scripts~~ feat(tasks): add usage args to Tera context in run scripts Dec 2, 2025

cursor bot reviewed Dec 2, 2025

View reviewed changes

Krut Patel and others added 4 commits December 2, 2025 04:56

Fix flag default

b373c01

[autofix.ci] apply automated fixes

3eae24c

Update test

746543b

Remove bad test

ea76f0c

No point in testing wrong behavior

jdx merged commit b0fffaf into jdx:main Dec 2, 2025
27 checks passed

mise-en-dev mentioned this pull request Dec 2, 2025

chore: release 2025.12.0 #7158

Merged

iamkroot deleted the tera-usage branch December 2, 2025 16:10

iamkroot pushed a commit to iamkroot/mise that referenced this pull request Dec 3, 2025

feat(tasks): Handle array defaults for variadic flags in usage spec

7ed332a

See jdx#7041

iamkroot mentioned this pull request Dec 3, 2025

feat(tasks): Handle array defaults for variadic flags in usage spec #7179

Closed

BrewTestBot mentioned this pull request Dec 4, 2025

mise 2025.12.0 Homebrew/homebrew-core#257058

Merged

Uh oh!

feat(tasks): add usage args to Tera context in run scripts #7041

feat(tasks): add usage args to Tera context in run scripts #7041

Conversation

iamkroot commented Nov 22, 2025 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

iamkroot commented Nov 30, 2025

Uh oh!

jdx commented Dec 1, 2025

Uh oh!

Uh oh!

jdx commented Dec 1, 2025

Uh oh!

jdx commented Dec 2, 2025

Uh oh!

cursor bot Dec 2, 2025

Choose a reason for hiding this comment

Bug: Variadic value flags get inconsistent types during parsing

Uh oh!

iamkroot Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat(tasks): add `usage` args to Tera context in run scripts #7041

feat(tasks): add `usage` args to Tera context in run scripts #7041

iamkroot commented Nov 22, 2025 •

edited by cursor bot

Loading