feat: add usage field to tasks (jdx#3746)

* chore: release 2024.12.16 (jdx#3720)

* feat: add `usage` field to tasks

---------

Co-authored-by: mise-en-dev <release@mise.jdx.dev>

docs/tasks/task-configuration.md

@@ -254,6 +254,20 @@ like to hide even the output that the task emits, use [`silent`](#silent).
 
 Suppress all output from the task. If set to `"stdout"` or `"stderr"`, only that stream will be suppressed.
 
+### `usage`
+
+- **Type**: `string`
+
+More advanced usage specs can be added to the task's `usage` field. This only applies to toml-tasks.
+
+```toml
+[tasks.test]
+usage = '''
+arg "file" description="The file to test" default="src/main.rs"
+'''
+run = 'cargo test {{arg(name="file")}}'
+```
+
 ## Vars
 
 Vars are variables that can be shared between tasks like environment variables but they are not

docs/tasks/toml-tasks.md

@@ -441,3 +441,15 @@ fi
 - `name`: The name of the flag. This is used for help/error messages.
 
 The value will be `true` if the flag is passed, and `false` otherwise.
+
+### Usage spec
+
+More advanced usage specs can be added to the task's `usage` field:
+
+```toml
+[tasks.test]
+usage = '''
+arg "file" description="The file to test" default="src/main.rs"
+'''
+run = 'cargo test {{arg(name="file")}}'
+```

e2e/tasks/test_task_run_toml

@@ -35,3 +35,12 @@ assert "mise run -E windows configtask" "configtask:windows"
 assert "mise run -P windows configtask" "configtask:windows"
 MISE_ENV=windows assert "mise run configtask" "configtask:windows"
 MISE_PROFILE=windows assert "mise run configtask" "configtask:windows"
+
+cat <<EOF >mise.toml
+[tasks.a]
+usage = '''
+arg "myarg" "myarg description" default="foo"
+'''
+run = 'echo {{arg(name="myarg")}}'
+EOF
+assert "mise run a" "foo"

mise.lock

@@ -15,13 +15,15 @@ backend = "core:bun"
 
 [tools.bun.checksums]
 "bun-darwin-aarch64.zip" = "sha256:64a70fe290bd6391a09d555d4e4e1a8df56543e526bb1381ab344a385348572c"
+"bun-linux-x64-baseline.zip" = "sha256:19584af4189e6434124a556e830427f0f44b7ebed8530eacf4fe369bd14b93d6"
 
 [tools.cargo-binstall]
 version = "1.10.17"
 backend = "aqua:cargo-bins/cargo-binstall"
 
 [tools.cargo-binstall.checksums]
 "cargo-binstall-aarch64-apple-darwin.zip" = "sha256:81abb7de75ef130844bb58965bdb93969afadd0821cf5e1e1bd0517e48963199"
+"cargo-binstall-x86_64-unknown-linux-musl.tgz" = "sha256:d073d4e8901e176b0f625845f9a0bbd926a063017991d7cc0c863e6b884d2d59"
 
 [tools."cargo:cargo-edit"]
 version = "0.13.0"
@@ -44,7 +46,7 @@ version = "0.2.3"
 backend = "cargo:toml-cli"
 
 [tools."cargo:usage-cli"]
-version = "1.7.3"
+version = "1.7.4"
 backend = "cargo:usage-cli"
 
 [tools.cosign]

src/task/mod.rs

@@ -80,6 +80,8 @@ pub struct Task {
     pub silent: bool,
     #[serde(default)]
     pub tools: IndexMap<String, String>,
+    #[serde(default)]
+    pub usage: String,
 
     // normal type
     #[serde(default, deserialize_with = "deserialize_arr")]
@@ -562,6 +564,7 @@ impl Default for Task {
             file: None,
             quiet: false,
             tools: Default::default(),
+            usage: "".to_string(),
         }
     }
 }

src/task/task_script_parser.rs

@@ -295,10 +295,11 @@ impl TaskScriptParser {
             })
             .collect();
         cmd.flags = input_flags.lock().unwrap().clone();
-        let spec = usage::Spec {
+        let mut spec = usage::Spec {
             cmd,
             ..Default::default()
         };
+        spec.merge(task.usage.parse()?);
 
         Ok((scripts, spec))
     }