feat: render task help via usage (#2760)

Cargo.toml

@@ -118,7 +118,7 @@ toml_edit = { version = "0.22", features = ["parse"] }
 ubi = { version = "0.2", default-features = false }
 url = "2.5.0"
 # usage-lib = { path = "../usage/lib", features = ["clap", "docs"] }
-usage-lib = { version = "0.10", features = ["clap", "docs"] }
+usage-lib = { version = "0.11", features = ["clap", "docs"] }
 versions = { version = "6.2.0", features = ["serde"] }
 vfox = "0.1"
 # vfox = {path="../vfox.rs"}

e2e/tasks/test_task_run

@@ -43,3 +43,4 @@ cat <<'EOF' >.mise/tasks/filetask
 echo "user=$usage_user"
 EOF
 assert "mise run filetask --user=jdx" "user=jdx"
+assert_contains "mise run filetask --help 2>&1 || true" "-u --user <user>"

registry.toml

@@ -747,7 +747,7 @@ unison = ["asdf:susurri/asdf-unison"]
 updatecli = ["asdf:updatecli/asdf-updatecli"]
 upt = ["asdf:ORCID/asdf-upt"]
 upx = ["asdf:jimmidyson/asdf-upx"]
-usage = ["asdf:jdx/mise-usage"]
+usage = [{full = "asdf:jdx/mise-usage", trust = true}]
 usql = ["asdf:itspngu/asdf-usql"]
 uv = ["asdf:asdf-community/asdf-uv"]
 v = ["asdf:jthegedus/asdf-v"]

src/cli/run.rs

@@ -7,6 +7,7 @@ use std::sync::Mutex;
 use std::time::SystemTime;
 
 use super::args::ToolArg;
+use crate::cli::Cli;
 use crate::cmd::CmdLineRunner;
 use crate::config::{CONFIG, SETTINGS};
 use crate::errors::Error;
@@ -52,12 +53,16 @@ use nix::sys::signal::SIGTERM;
 ///     EOF
 ///     $ mise run build
 #[derive(Debug, clap::Args)]
-#[clap(visible_alias = "r", verbatim_doc_comment, after_long_help = AFTER_LONG_HELP)]
+#[clap(visible_alias = "r", verbatim_doc_comment, disable_help_flag = true, after_long_help = AFTER_LONG_HELP)]
 pub struct Run {
     /// Tasks to run
     /// Can specify multiple tasks by separating with `:::`
     /// e.g.: mise run task1 arg1 arg2 ::: task2 arg1 arg2
-    #[clap(verbatim_doc_comment, default_value = "default")]
+    #[clap(
+        allow_hyphen_values = true,
+        verbatim_doc_comment,
+        default_value = "default"
+    )]
     pub task: String,
 
     /// Arguments to pass to the tasks. Use ":::" to separate tasks.
@@ -117,6 +122,14 @@ pub struct Run {
 
 impl Run {
     pub fn run(self) -> Result<()> {
+        if self.task == "-h" {
+            self.get_clap_command().print_help()?;
+            return Ok(());
+        }
+        if self.task == "--help" {
+            self.get_clap_command().print_long_help()?;
+            return Ok(());
+        }
         SETTINGS.ensure_experimental("`mise run`")?;
         time!("run init");
         let task_list = self.get_task_lists()?;
@@ -126,6 +139,14 @@ impl Run {
         Ok(())
     }
 
+    fn get_clap_command(&self) -> clap::Command {
+        Cli::command()
+            .get_subcommands()
+            .find(|s| s.get_name() == "run")
+            .unwrap()
+            .clone()
+    }
+
     fn get_task_lists(&self) -> Result<Vec<Task>> {
         once(&self.task)
             .chain(self.args.iter())
@@ -149,7 +170,7 @@ impl Run {
                     .collect_vec();
                 if tasks.is_empty() {
                     if t != "default" {
-                        err_no_task(&t)?;
+                        self.err_no_task(&t)?;
                     }
 
                     Ok(vec![self.prompt_for_task()?])
@@ -546,30 +567,31 @@ impl Run {
         // TODO
         Ok(())
     }
-}
 
-fn err_no_task(name: &str) -> Result<()> {
-    if let Some(cwd) = &*dirs::CWD {
-        let includes = CONFIG.task_includes_for_dir(cwd);
-        let path = includes
-            .iter()
-            .map(|d| d.join(name))
-            .find(|d| d.is_file() && !file::is_executable(d));
-        if let Some(path) = path {
-            warn!(
-                "no task {} found, but a non-executable file exists at {}",
-                style::ered(name),
-                display_path(&path)
-            );
-            let yn =
-                prompt::confirm("Mark this file as executable to allow it to be run as a task?")?;
-            if yn {
-                file::make_executable(&path)?;
-                info!("marked as executable, try running this task again");
+    fn err_no_task(&self, name: &str) -> Result<()> {
+        if let Some(cwd) = &*dirs::CWD {
+            let includes = CONFIG.task_includes_for_dir(cwd);
+            let path = includes
+                .iter()
+                .map(|d| d.join(name))
+                .find(|d| d.is_file() && !file::is_executable(d));
+            if let Some(path) = path {
+                warn!(
+                    "no task {} found, but a non-executable file exists at {}",
+                    style::ered(name),
+                    display_path(&path)
+                );
+                let yn = prompt::confirm(
+                    "Mark this file as executable to allow it to be run as a task?",
+                )?;
+                if yn {
+                    file::make_executable(&path)?;
+                    info!("marked as executable, try running this task again");
+                }
             }
         }
+        bail!("no task {} found", style::ered(name));
     }
-    bail!("no task {} found", style::ered(name));
 }
 
 fn is_glob_pattern(path: &str) -> bool {

src/cli/tasks/snapshots/mise__cli__tasks__info__tests__task_info_json-2.snap

@@ -52,6 +52,7 @@ expression: output
     "config": {
       "props": {}
     },
+    "disable_help": null,
     "name": "test",
     "usage": "",
     "version": null

src/cli/tasks/snapshots/mise__cli__tasks__info__tests__task_info_json.snap

@@ -95,6 +95,7 @@ expression: output
     "config": {
       "props": {}
     },
+    "disable_help": null,
     "name": "filetask",
     "usage": "",
     "version": null

tasks.md

@@ -68,8 +68,6 @@ run a command inside of development docker container
 
 ## `filetask`
 
-- Depends: lint, build
-
 **Usage**: `filetask [-f --force] [-u --user <user>] <file> <arg_with_default>`
 
 **Aliases**: `ft`
@@ -82,10 +80,18 @@ This is a test build script
 
 The file to write
 
+##### Default
+
+`file.txt`
+
 #### `<arg_with_default>`
 
 An arg with a default
 
+##### Default
+
+`mydefault`
+
 ### Flags
 
 #### `-f --force`

tasks/filetask

@@ -6,7 +6,6 @@
 #USAGE arg "<arg_with_default>" help="An arg with a default" default="mydefault"
 
 #MISE description="This is a test build script"
-#MISE depends=["lint", "build"]
 #MISE sources=[".test-tool-versions"]
 #MISE outputs=["$MISE_PROJECT_ROOT/test/test-build-output.txt"]
 #MISE env={TEST_BUILDSCRIPT_ENV_VAR = "VALID"}