feat: add support for task templates (#269)

Author: hverlin

README.md

@@ -58,7 +58,7 @@ To enable auto-configuration, set [`mise.configureExtensionsAutomatically`](http
 
 **Important:** By default, tools from your global mise configuration (`~/.config/mise/config.toml`) are included when auto-configuring other VS Code extensions ([`mise.configureExtensionsIncludeGlobalTools`](https://hverlin.github.io/mise-vscode/reference/settings/#miseconfigureextensionsincludeglobaltools) is `true` for backward compatibility). You can set it to `false` to keep your `.vscode/settings.json` clean and ensure extensions are only configured for tools actually used in your project.
 
-## ✨ Features
+## Features
 
 The mise-vscode extension integrates mise's core functionality into VS Code, helping you manage your development environment directly from the editor. You can handle task running, tool versions, and environment variables through a simple interface. Here's what's available:
 
@@ -80,6 +80,8 @@ The mise-vscode extension integrates mise's core functionality into VS Code, hel
 - 📝 View task definitions
 - ➕ Create new toml & file tasks
 - ⚡ Autocompletion of task dependencies
+- 🧬 Autocompletion, hover, go to definition and find references for
+  [task templates](https://mise.jdx.dev/tasks/templates.html) (`extends`)
 - 🕸️ View graph of task dependencies
 
 ### [Tool Management](https://hverlin.github.io/mise-vscode/reference/tools/)

bun-preload-test.ts

@@ -15,6 +15,26 @@ mock.module("vscode", () => {
 		) {}
 	}
 
+	class MarkdownString {
+		public supportHtml = false;
+		constructor(public value = "") {}
+
+		appendMarkdown(markdown: string) {
+			this.value += markdown;
+			return this;
+		}
+
+		appendText(text: string) {
+			this.value += text;
+			return this;
+		}
+
+		appendCodeblock(code: string, language = "") {
+			this.value += `\n\`\`\`${language}\n${code}\n\`\`\`\n`;
+			return this;
+		}
+	}
+
 	return {
 		workspace: {},
 		window: {
@@ -25,7 +45,16 @@ mock.module("vscode", () => {
 			createOutputChannel: () => {},
 		},
 		ConfigurationTarget: {},
+		MarkdownString,
 		Position,
 		Range: Range,
+		Uri: {
+			file: (fsPath: string) => ({
+				fsPath,
+				path: fsPath,
+				scheme: "file",
+				toString: () => `file://${fsPath}`,
+			}),
+		},
 	};
 });

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

@@ -146,6 +146,41 @@ context menu in the activity bar:
 This requires mise `2026.8.1` or later. Nothing is shown for tasks that do not
 enable the cache.
 
+## Task templates
+
+[Task templates](https://mise.jdx.dev/tasks/templates.html) are reusable task
+definitions declared in a `[task_templates.<name>]` section. A task picks one up
+with `extends = "<name>"`, and can override any of its fields:
+
+```toml
+[task_templates."python:build"]
+description = "Build a python package"
+run = "uv build"
+tools = { python = "3.12", uv = "latest" }
+
+[tasks.build]
+extends = "python:build"
+run = "uv build --wheel" # overrides the template command
+```
+
+The extension resolves templates the way mise does, from the config file
+declaring the task and from its parent config files, which makes them
+particularly useful in a [monorepo](#monorepo-tasks). It provides:
+
+- **Autocompletion** of the template names in `extends = "<name>"`, showing the
+  declared fields and which config file each template comes from
+- **Hover** on `extends = "<name>"`, showing the template it resolves to, and on
+  a `[task_templates.<name>]` declaration, showing how many tasks extend it
+- **Go to definition** from `extends = "<name>"` to the `[task_templates.<name>]`
+  entry, in the same file or in a parent config file
+- **Find references** from a template declaration to every task extending it,
+  anywhere in the workspace
+- Task templates in the outline view, and `task_template` / `task_extends`
+  snippets
+
+Task hovers show the template a task extends. The fields shown for the task
+itself are the ones mise resolved, i.e. after the template has been merged in.
+
 ## Monorepo tasks
 
 The extension supports
@@ -173,8 +208,8 @@ Navigation understands all the ways tasks can reference each other:
   project depends on, following the workspace projects graph
 - task aliases (`alias = "fmt"`), including in other projects
 
-Tasks declared with `extends = "<name>"` support go-to-definition to the
-`[task_templates.<name>]` entry, in the same file or a parent config file.
+[Task templates](#task-templates) declared in the monorepo root config are
+resolved for the tasks of every project extending them.
 Dependencies added by `[monorepo.task_defaults]` in the root config are shown
 in the task tooltips and included when searching for task references.
 

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

@@ -68,6 +68,12 @@ syntax highlighting even though they have no `.toml` extension.
 
 Code completion is provided for `depends = ["task_name"]`, `depends_post = ["task_name"]`, `wait_for = ["task_name"]`.
 
+`extends = "template_name"` completes the
+[task templates](https://mise.jdx.dev/tasks/templates.html) declared in the file
+being edited and in its parent config files. See the
+[task templates section](/mise-vscode/reference/tasks/#task-templates) of the tasks
+reference for the hover, go-to-definition, and find-references support.
+
 ### Task arguments (usage spec)
 
 Task arguments are declared with the
@@ -120,6 +126,9 @@ This extension adds the following code lens features:
 
 - Cmd/Ctrl+Click on an included file will open that file (example:
   `include = ["tasks.toml"`])
+- Cmd/Ctrl+Click on `extends = "template_name"` opens the
+  `[task_templates.template_name]` declaration; _Find all references_ on a
+  declaration lists every task extending it
 
 ### Syntax highlighting for shebang
 

snippets/toml-tasks-snippets.json

@@ -25,6 +25,15 @@
 		"description": "Create a simple mise task",
 		"body": ["[tasks.${1:taskname}]", "run = \"echo 'running...'\"", "$0"]
 	},
+	"tomlTaskTemplate": {
+		"prefix": "task_template",
+		"description": "Create a reusable task template that tasks can extend",
+		"body": [
+			"[task_templates.${1:my:template}]",
+			"${2:description = '${3:Template description}'\n}${4:tools = { ${5:node} = \"${6:latest}\" }\n}run = \"echo 'running...'\"",
+			"$0"
+		]
+	},
 	"tomlTaskScript": {
 		"prefix": "task_script",
 		"description": "Create a mise task with multiline script",

src/e2e-tests/fixtures/monorepo-workspace/crates/agent/mise.toml

@@ -1,4 +1,6 @@
 [tasks.build]
+# overrides the description and the run command of the root task template
+extends = "rust:build"
 description = "Depends on a task of another crate"
 depends = ["//crates/protocol:build"]
 run = "echo 'Building agent crate'"

src/e2e-tests/fixtures/monorepo-workspace/crates/protocol/mise.toml

@@ -1,3 +1,3 @@
 [tasks.build]
-description = "Build the protocol crate"
-run = "echo 'Building protocol crate'"
+# the description and the run command come from the root task template
+extends = "rust:build"

src/e2e-tests/fixtures/monorepo-workspace/mise.toml

@@ -22,6 +22,11 @@ depends = ["^build"]
 description = "Show information about the project"
 run = "echo 'project info'"
 
+# namespaced template name, extended by several crates
+[task_templates."rust:build"]
+description = "Build a rust crate"
+run = "echo 'Building crate'"
+
 [settings]
 # package.json script tasks and `mise tasks graph` are experimental-gated
 experimental = true

src/e2e-tests/monorepo/monorepo-tasks.e2e.ts

@@ -427,6 +427,144 @@ suite("Monorepo Tasks Test Suite", function () {
 		assert.equal(targetRange.start.line, expectedLine);
 	});
 
+	test("Should complete task template names in extends", async () => {
+		const uri = vscode.Uri.file(
+			path.join(workspaceRoot, "crates", "protocol", "mise.toml"),
+		);
+		const document = await vscode.workspace.openTextDocument(uri);
+
+		const lineIndex = document
+			.getText()
+			.split("\n")
+			.findIndex((line) => line.includes("extends ="));
+		assert.ok(lineIndex >= 0, "extends line should be found in the fixture");
+		// just after the opening quote, i.e. with nothing typed yet
+		const character = document.lineAt(lineIndex).text.indexOf('"') + 1;
+
+		const completions =
+			await vscode.commands.executeCommand<vscode.CompletionList>(
+				"vscode.executeCompletionItemProvider",
+				uri,
+				new vscode.Position(lineIndex, character),
+			);
+		const labels = completions.items.map((item) =>
+			typeof item.label === "string" ? item.label : item.label.label,
+		);
+
+		// both templates of the root config are offered, not only the local one
+		for (const expected of ["rust:build", "project-info"]) {
+			assert.ok(
+				labels.includes(expected),
+				`expected ${expected} in ${JSON.stringify(labels)}`,
+			);
+		}
+	});
+
+	test("Should show the resolved template when hovering extends", async () => {
+		const uri = vscode.Uri.file(
+			path.join(workspaceRoot, "crates", "protocol", "mise.toml"),
+		);
+		const document = await vscode.workspace.openTextDocument(uri);
+
+		const lineIndex = document
+			.getText()
+			.split("\n")
+			.findIndex((line) => line.includes("extends ="));
+		assert.ok(lineIndex >= 0, "extends line should be found in the fixture");
+		const character = document.lineAt(lineIndex).text.indexOf("rust:build") + 1;
+
+		const hovers =
+			(await vscode.commands.executeCommand<vscode.Hover[]>(
+				"vscode.executeHoverProvider",
+				uri,
+				new vscode.Position(lineIndex, character),
+			)) ?? [];
+		const hoverText = hovers
+			.flatMap((hover) => hover.contents)
+			.map((content) =>
+				typeof content === "string"
+					? content
+					: (content as { value: string }).value,
+			)
+			.join("\n");
+
+		assert.ok(
+			hoverText.includes("Build a rust crate"),
+			`the hover should describe the template, got ${hoverText}`,
+		);
+		assert.ok(
+			hoverText.includes("echo 'Building crate'"),
+			`the hover should show the template command, got ${hoverText}`,
+		);
+		// the template comes from the root config, not from this one
+		assert.ok(
+			hoverText.includes("mise.toml"),
+			`the hover should link to the declaring config, got ${hoverText}`,
+		);
+	});
+
+	test("Should find every task extending a task template", async () => {
+		const uri = vscode.Uri.file(path.join(workspaceRoot, "mise.toml"));
+		const document = await vscode.workspace.openTextDocument(uri);
+
+		const headerLine = document
+			.getText()
+			.split("\n")
+			.findIndex((line) => line.includes('[task_templates."rust:build"]'));
+		assert.ok(headerLine >= 0, "the template header should be in the fixture");
+		const character = document.lineAt(headerLine).text.indexOf("rust:build");
+
+		const locations = await vscode.commands.executeCommand<vscode.Location[]>(
+			"vscode.executeReferenceProvider",
+			uri,
+			new vscode.Position(headerLine, character),
+		);
+		const locationPaths = locations.map((location) => location.uri.path);
+
+		for (const expected of [
+			"crates/agent/mise.toml",
+			"crates/protocol/mise.toml",
+		]) {
+			assert.ok(
+				locationPaths.some((locationPath) => locationPath.endsWith(expected)),
+				`expected an extends in ${expected}, got ${JSON.stringify(locationPaths)}`,
+			);
+		}
+	});
+
+	test("Should report how many tasks extend a template on hover", async () => {
+		const uri = vscode.Uri.file(path.join(workspaceRoot, "mise.toml"));
+		const document = await vscode.workspace.openTextDocument(uri);
+
+		const headerLine = document
+			.getText()
+			.split("\n")
+			.findIndex((line) => line.includes('[task_templates."rust:build"]'));
+		assert.ok(headerLine >= 0, "the template header should be in the fixture");
+		const character =
+			document.lineAt(headerLine).text.indexOf("rust:build") + 1;
+
+		const hovers =
+			(await vscode.commands.executeCommand<vscode.Hover[]>(
+				"vscode.executeHoverProvider",
+				uri,
+				new vscode.Position(headerLine, character),
+			)) ?? [];
+		const hoverText = hovers
+			.flatMap((hover) => hover.contents)
+			.map((content) =>
+				typeof content === "string"
+					? content
+					: (content as { value: string }).value,
+			)
+			.join("\n");
+
+		assert.ok(
+			hoverText.includes("Extended by 2 tasks"),
+			`the hover should count the extending tasks, got ${hoverText}`,
+		);
+	});
+
 	test("Should find dependent tasks across the monorepo", async () => {
 		const uri = vscode.Uri.file(
 			path.join(workspaceRoot, "projects", "frontend", "mise.toml"),

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

@@ -8,6 +8,8 @@ import * as vscode from "vscode";
 
 const execFileAsync = promisify(execFile);
 
+const CACHE_REFRESH_DEADLINE_MS = 20_000;
+
 /**
  * The experimental task output cache (mise 2026.8.1+): code lens, hover and the
  * cache commands. The fixture keeps its artifacts in a workspace-local cache
@@ -151,8 +153,10 @@ suite("Task Cache Test Suite", function () {
 	test("never predicts for a task declaring command inputs", async () => {
 		await runMise(["run", "--force", "probe"]);
 
-		// the entry list is cached briefly, wait for the watcher to invalidate it
-		const deadline = Date.now() + 6_000;
+		// the entry list is cached briefly: the artifact watcher normally
+		// invalidates it right away, but the file watcher can stay silent on a
+		// loaded CI runner, so wait past the cache ttl that backs it up
+		const deadline = Date.now() + CACHE_REFRESH_DEADLINE_MS;
 		let hoverText = await getHoverText("[tasks.probe]");
 		while (!hoverText.includes("Cache:") && Date.now() < deadline) {
 			await new Promise((resolve) => setTimeout(resolve, 250));
@@ -238,9 +242,10 @@ suite("Task Cache Test Suite", function () {
 
 		await runMise(["run", "--force", "build"]);
 
-		// the document is never touched: the artifact watcher is what invalidates
-		// the cached `mise cache task` output
-		const deadline = Date.now() + 6_000;
+		// the document is never touched: the cached `mise cache task` output is
+		// invalidated by the artifact watcher, or by its ttl when the file watcher
+		// misses the run
+		const deadline = Date.now() + CACHE_REFRESH_DEADLINE_MS;
 		let title = await cacheLensTitle();
 		while (!/Cache · \d/.test(title ?? "") && Date.now() < deadline) {
 			await new Promise((resolve) => setTimeout(resolve, 250));