fix: improve usage support (#255)

Author: hverlin

README.md

@@ -63,13 +63,16 @@ The mise-vscode extension integrates mise's core functionality into VS Code, hel
 ### [mise.toml Language Support](https://hverlin.github.io/mise-vscode/reference/misetoml-language-support/)
 - 📝 Syntax highlighting for `mise.toml` files (and [tera templates](https://mise.jdx.dev/templates.html))
 - 📚 Autocompletion for `mise.toml` files
+- 🧩 Autocompletion & hover for [task arguments](https://mise.jdx.dev/tasks/task-arguments.html)
+  (`usage` field, `#USAGE`/`#MISE` comments in file tasks, `$usage_*` variables)
 - 🔗 Go to definition, find references for mise tasks
 
 ### [Task Management](https://hverlin.github.io/mise-vscode/reference/tasks/)
 
 - 🔍 Automatic detection of [mise tasks](https://mise.jdx.dev/tasks/)
 - ⚡ Run tasks directly from, `mise.toml` files, file tasks, the command palette
-  or the activity bar (arguments are supported)
+  or the activity bar (task arguments are prompted for, with choices and
+  default values from the [usage spec](https://mise.jdx.dev/tasks/task-arguments.html))
 - 📝 View task definitions
 - ➕ Create new toml & file tasks
 - ⚡ Autocompletion of task dependencies

docs/src/content/docs/reference/Tasks.md

@@ -31,6 +31,22 @@ You have several ways to run a task with the extension:
 Click on the run button to run the task. If some option/arguments are required,
 you will be prompted to enter them.
 
+### Task arguments
+
+If the task declares arguments with the
+[`usage` field](https://mise.jdx.dev/tasks/task-arguments.html) (or `#USAGE`
+comments in file tasks), the extension prompts for them before running:
+
+- arguments with `choices` are picked from a list
+- `default` values are pre-filled
+- the `help` text of each arg/flag is shown in the prompt
+- optional arguments can be skipped
+
+See
+[mise.toml language support](/mise-vscode/reference/misetoml-language-support/#task-arguments-usage-spec)
+for the editor support (autocompletion, hover, syntax highlighting) of the
+usage spec.
+
 ### Using the mise activity bar
 
 ![task-run-activity-bar.png](../../../assets/task-run-activity-bar.png)
@@ -90,6 +106,11 @@ You can create a file task or a toml task directly from the activity bar
 Using the command palette: `cmd|ctrl+shift+p`, search for
 `Mise: Create File task` or `Mise: Create Toml Task`
 
+New file tasks are created with a working example of
+[task arguments](https://mise.jdx.dev/tasks/task-arguments.html) (`#USAGE`
+flag, argument with a default value, custom completion, and the corresponding
+`$usage_*` variables in the script).
+
 ## Task dependencies
 
 You can visualize the dependencies of a task by using the `Mise: Visualize Tasks Dependencies` command.

docs/src/content/docs/reference/mise.toml-language-support.md

@@ -43,10 +43,55 @@ Tool names and versions are autocompleted in the `tools` section of a `mise.toml
 
 ![Screenshot showing autocompletion of tool version](./autocomplete-tool-version.png)
 
+In `.tool-versions` files, backend prefixes (`core:`, `npm:`, `cargo:`, ...) are
+also autocompleted, and typing a prefix such as `core:` suggests the registry
+tools of that backend (e.g. `core:node`).
+
 #### Autocompletion for tasks
 
 Code completion is provided for `depends = ["task_name"]`, `depends_post = ["task_name"]`, `wait_for = ["task_name"]`.
 
+### Task arguments (usage spec)
+
+Task arguments are declared with the
+[`usage` field](https://mise.jdx.dev/tasks/task-arguments.html) of a task,
+using the [usage spec](https://usage.jdx.dev/spec/). The extension provides:
+
+- **Syntax highlighting** of `usage = '''...'''` blocks (KDL)
+- **Context-aware autocompletion**: directives (`arg`, `flag`, `complete`) at
+  the start of a line, the attributes valid for that directive after it
+  (`help`, `default`, `choices` blocks, `count`, `negate`, ...), without
+  repeating attributes that are already set
+- **Hover documentation** for directives and attributes
+- **`$usage_*` variable completion**: typing `$` in a multiline `run` block
+  suggests the `usage_*` environment variables derived from the args and
+  flags of that task
+
+```toml
+[tasks.deploy]
+usage = '''
+arg "<environment>" help="Target environment" {
+  choices "dev" "staging" "prod"
+}
+flag "-v --verbose" help="Enable verbose output"
+'''
+run = '''
+echo "Deploying to ${usage_environment?}"
+'''
+```
+
+#### File tasks
+
+The same support is available in shell
+[file tasks](https://mise.jdx.dev/tasks/file-tasks.html):
+
+- `#USAGE` lines get usage spec syntax highlighting, autocompletion, and hover
+- `#MISE` lines are highlighted as TOML, with autocompletion and hover for the
+  [task configuration keys](https://mise.jdx.dev/tasks/task-configuration.html)
+  (`description`, `alias`, `depends`, `sources`, ...)
+- Typing `$` in the script body suggests the `usage_*` variables from the
+  `#USAGE` lines
+
 ### Code lens features
 
 This extension adds the following code lens features:

package.json

@@ -126,6 +126,13 @@
         "scopeName": "source.mise.shell",
         "path": "./syntaxes/shell.json"
       },
+      {
+        "injectTo": [
+          "source.shell"
+        ],
+        "scopeName": "inline.mise-usage",
+        "path": "./syntaxes/usage-shell.json"
+      },
       {
         "injectTo": [
           "source.toml"
@@ -180,6 +187,13 @@
         "path": "./snippets/file-tasks-snippets.json"
       }
     ],
+    "configurationDefaults": {
+      "[toml]": {
+        "editor.quickSuggestions": {
+          "strings": "on"
+        }
+      }
+    },
     "configuration": {
       "title": "Mise",
       "properties": {

snippets/file-tasks-snippets.json

@@ -11,5 +11,15 @@
 			"#MISE depends=[${5:\"dependency\"}]",
 			"$0"
 		]
+	},
+	"mise File Task Usage Spec": {
+		"prefix": "mise-task-usage",
+		"scope": "shellscript",
+		"description": "Define file task arguments with the usage spec",
+		"body": [
+			"#USAGE arg \"<${1:file}>\" help=\"${2:File to use}\"",
+			"#USAGE flag \"-v --verbose\" help=\"Enable verbose output\"",
+			"$0"
+		]
 	}
 }

snippets/toml-tasks-snippets.json

@@ -117,6 +117,19 @@
 			"$0"
 		]
 	},
+	"tomlTaskUsage": {
+		"prefix": "task_usage",
+		"description": "Create a mise task with arguments defined with the usage spec",
+		"body": [
+			"[tasks.${1:my_task}]",
+			"${2:description = '${3:Task description}'\n}usage = '''",
+			"arg \"<${4:file}>\" help=\"${5:File to use}\"",
+			"flag \"-v --verbose\" help=\"Enable verbose output\"",
+			"'''",
+			"run = 'echo \"\\${usage_$4?}\"'",
+			"$0"
+		]
+	},
 	"tomlTaskFull": {
 		"prefix": "task_full",
 		"description": "Create a mise task with all possible options",
@@ -131,10 +144,13 @@
 			"sources = [${8:'src/**/*'}]",
 			"outputs = [${9:'dist/**/*'}]",
 			"shell = '${10:bash -c}'",
-			"run = [",
-			"    \"echo 'running step 1...'\",",
-			"    \"echo 'running step 2...'\"",
-			"]",
+			"usage = '''",
+			"arg \"<${11:file}>\" help=\"${12:File to use}\"",
+			"'''",
+			"run = '''",
+			"echo 'running step 1...'",
+			"echo \"running step 2 with \\${usage_${11}?}\"",
+			"'''",
 			"$0"
 		]
 	}

src/e2e-tests/fixtures/task-execution-workspace/file-task.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+#USAGE flag "--force" help="Force the run"
+#USAGE f
+#MISE d
+echo "file task fixture for usage completions"
+echo $usage_

src/e2e-tests/fixtures/task-execution-workspace/mise.toml

@@ -4,3 +4,17 @@ run = "echo 'Hello from mise test task'"
 
 [tasks.echo-hello]
 run = "echo 'Hello, World!'"
+
+[tasks.greet]
+description = "Greet someone"
+usage = '''
+arg "<name>" help="Name to greet" {
+  choices "alice" "bob"
+}
+flag "--greeting <greeting>" help="Greeting to use" default="hello"
+flag "-l --loud" help="Shout the greeting"
+'''
+run = '''
+echo "${usage_greeting?} ${usage_name?}"
+echo $usage_
+'''

src/e2e-tests/task-execution.e2e.ts

@@ -41,7 +41,7 @@ suite("Task Execution Test Suite", function () {
 
 		assert.deepEqual(
 			tasks.map((t) => t.name),
-			["echo-hello", "test-e2e"],
+			["echo-hello", "greet", "test-e2e"],
 		);
 
 		const echoTask = tasks.find((t) => t.name === "echo-hello");

src/e2e-tests/tool-versions/tool-versions.e2e.ts

@@ -79,6 +79,58 @@ suite("Tool Versions File Test Suite", function () {
 		);
 	});
 
+	test("completes backend prefixes in the first token of a line", async () => {
+		const completions =
+			await vscode.commands.executeCommand<vscode.CompletionList>(
+				"vscode.executeCompletionItemProvider",
+				document.uri,
+				new vscode.Position(lineOf("nodejs 20.11.0"), 0),
+			);
+
+		const labels = completions.items.map((item) =>
+			typeof item.label === "string" ? item.label : item.label.label,
+		);
+		assert.ok(
+			labels.includes("core:") && labels.includes("npm:"),
+			`Expected backend prefixes (core:, npm:) in completions, got ${labels.length} items`,
+		);
+	});
+
+	test("completes registry tools after a backend prefix", async () => {
+		const editor = await vscode.window.showTextDocument(document);
+		const lastLine = document.lineCount - 1;
+		await editor.edit((edit) => {
+			edit.insert(
+				new vscode.Position(lastLine, document.lineAt(lastLine).text.length),
+				"\ncore:",
+			);
+		});
+
+		try {
+			const backendLine = lineOf("core:");
+			const completions =
+				await vscode.commands.executeCommand<vscode.CompletionList>(
+					"vscode.executeCompletionItemProvider",
+					document.uri,
+					new vscode.Position(backendLine, "core:".length),
+				);
+
+			const labels = completions.items.map((item) =>
+				typeof item.label === "string" ? item.label : item.label.label,
+			);
+			assert.ok(
+				labels.includes("core:node"),
+				`Expected "core:node" after the core: prefix, got: ${labels.slice(0, 20).join(", ")}`,
+			);
+			assert.ok(
+				labels.every((label) => label.startsWith("core:")),
+				`Only core: tools should be offered after the core: prefix, got: ${labels.slice(0, 20).join(", ")}`,
+			);
+		} finally {
+			await vscode.commands.executeCommand("undo");
+		}
+	});
+
 	test("provides hover for declared tools", async () => {
 		const shellcheckLine = lineOf("shellcheck 0.10.0");
 		const hovers =