Add support for command argument hints

Author: mrubens

src/core/webview/webviewMessageHandler.ts

@@ -2375,6 +2375,7 @@ export const webviewMessageHandler = async (
 					source: command.source,
 					filePath: command.filePath,
 					description: command.description,
+					argumentHint: command.argumentHint,
 				}))
 
 				await provider.postMessageToWebview({

src/services/command/__tests__/frontmatter-commands.spec.ts

@@ -43,6 +43,7 @@ npm run build
 				source: "project",
 				filePath: path.join("/test/cwd", ".roo", "commands", "setup.md"),
 				description: "Sets up the development environment",
+				argumentHint: undefined,
 			})
 		})
 
@@ -66,6 +67,7 @@ npm run build
 				source: "project",
 				filePath: path.join("/test/cwd", ".roo", "commands", "setup.md"),
 				description: undefined,
+				argumentHint: undefined,
 			})
 		})
 
@@ -108,6 +110,7 @@ Command content here.`
 				source: "project",
 				filePath: path.join("/test/cwd", ".roo", "commands", "setup.md"),
 				description: undefined,
+				argumentHint: undefined,
 			})
 		})
 
@@ -142,6 +145,7 @@ Global setup instructions.`
 				source: "project",
 				filePath: path.join("/test/cwd", ".roo", "commands", "setup.md"),
 				description: "Project-specific setup",
+				argumentHint: undefined,
 			})
 		})
 
@@ -168,10 +172,118 @@ Global setup instructions.`
 				source: "global",
 				filePath: expect.stringContaining(path.join(".roo", "commands", "setup.md")),
 				description: "Global setup command",
+				argumentHint: undefined,
 			})
 		})
 	})
 
+	describe("argument-hint functionality", () => {
+		it("should load command with argument-hint from frontmatter", async () => {
+			const commandContent = `---
+description: Create a new release of the Roo Code extension
+argument-hint: patch | minor | major
+---
+
+# Release Command
+
+Create a new release.`
+
+			mockFs.stat = vi.fn().mockResolvedValue({ isDirectory: () => true })
+			mockFs.readFile = vi.fn().mockResolvedValue(commandContent)
+
+			const result = await getCommand("/test/cwd", "release")
+
+			expect(result).toEqual({
+				name: "release",
+				content: "# Release Command\n\nCreate a new release.",
+				source: "project",
+				filePath: path.join("/test/cwd", ".roo", "commands", "release.md"),
+				description: "Create a new release of the Roo Code extension",
+				argumentHint: "patch | minor | major",
+			})
+		})
+
+		it("should handle command with both description and argument-hint", async () => {
+			const commandContent = `---
+description: Deploy application to environment
+argument-hint: staging | production
+author: DevOps Team
+---
+
+# Deploy Command
+
+Deploy the application.`
+
+			mockFs.stat = vi.fn().mockResolvedValue({ isDirectory: () => true })
+			mockFs.readFile = vi.fn().mockResolvedValue(commandContent)
+
+			const result = await getCommand("/test/cwd", "deploy")
+
+			expect(result).toEqual({
+				name: "deploy",
+				content: "# Deploy Command\n\nDeploy the application.",
+				source: "project",
+				filePath: path.join("/test/cwd", ".roo", "commands", "deploy.md"),
+				description: "Deploy application to environment",
+				argumentHint: "staging | production",
+			})
+		})
+
+		it("should handle empty argument-hint in frontmatter", async () => {
+			const commandContent = `---
+description: Test command
+argument-hint: ""
+---
+
+# Test Command
+
+Test content.`
+
+			mockFs.stat = vi.fn().mockResolvedValue({ isDirectory: () => true })
+			mockFs.readFile = vi.fn().mockResolvedValue(commandContent)
+
+			const result = await getCommand("/test/cwd", "test")
+
+			expect(result?.argumentHint).toBeUndefined()
+		})
+
+		it("should handle whitespace-only argument-hint in frontmatter", async () => {
+			const commandContent = `---
+description: Test command
+argument-hint: "   "
+---
+
+# Test Command
+
+Test content.`
+
+			mockFs.stat = vi.fn().mockResolvedValue({ isDirectory: () => true })
+			mockFs.readFile = vi.fn().mockResolvedValue(commandContent)
+
+			const result = await getCommand("/test/cwd", "test")
+
+			expect(result?.argumentHint).toBeUndefined()
+		})
+
+		it("should handle non-string argument-hint in frontmatter", async () => {
+			const commandContent = `---
+description: Test command
+argument-hint: 123
+---
+
+# Test Command
+
+Test content.`
+
+			mockFs.stat = vi.fn().mockResolvedValue({ isDirectory: () => true })
+			mockFs.readFile = vi.fn().mockResolvedValue(commandContent)
+
+			const result = await getCommand("/test/cwd", "test")
+
+			expect(result?.argumentHint).toBeUndefined()
+		})
+	})
+
 	describe("getCommands with frontmatter", () => {
 		it("should load multiple commands with descriptions", async () => {
 			const setupContent = `---
@@ -215,14 +327,62 @@ Build instructions without frontmatter.`
 					expect.objectContaining({
 						name: "setup",
 						description: "Sets up the development environment",
+						argumentHint: undefined,
 					}),
 					expect.objectContaining({
 						name: "deploy",
 						description: "Deploys the application to production",
+						argumentHint: undefined,
 					}),
 					expect.objectContaining({
 						name: "build",
 						description: undefined,
+						argumentHint: undefined,
+					}),
+				]),
+			)
+		})
+
+		it("should load multiple commands with argument hints", async () => {
+			const releaseContent = `---
+description: Create a new release
+argument-hint: patch | minor | major
+---
+
+# Release Command
+
+Create a release.`
+
+			const deployContent = `---
+description: Deploy to environment
+argument-hint: staging | production
+---
+
+# Deploy Command
+
+Deploy the app.`
+
+			mockFs.stat = vi.fn().mockResolvedValue({ isDirectory: () => true })
+			mockFs.readdir = vi.fn().mockResolvedValue([
+				{ name: "release.md", isFile: () => true },
+				{ name: "deploy.md", isFile: () => true },
+			])
+			mockFs.readFile = vi.fn().mockResolvedValueOnce(releaseContent).mockResolvedValueOnce(deployContent)
+
+			const result = await getCommands("/test/cwd")
+
+			expect(result).toHaveLength(2)
+			expect(result).toEqual(
+				expect.arrayContaining([
+					expect.objectContaining({
+						name: "release",
+						description: "Create a new release",
+						argumentHint: "patch | minor | major",
+					}),
+					expect.objectContaining({
+						name: "deploy",
+						description: "Deploy to environment",
+						argumentHint: "staging | production",
 					}),
 				]),
 			)

src/services/command/commands.ts

@@ -9,6 +9,7 @@ export interface Command {
 	source: "global" | "project"
 	filePath: string
 	description?: string
+	argumentHint?: string
 }
 
 /**
@@ -70,6 +71,7 @@ async function tryLoadCommand(
 
 			let parsed
 			let description: string | undefined
+			let argumentHint: string | undefined
 			let commandContent: string
 
 			try {
@@ -79,10 +81,15 @@ async function tryLoadCommand(
 					typeof parsed.data.description === "string" && parsed.data.description.trim()
 						? parsed.data.description.trim()
 						: undefined
+				argumentHint =
+					typeof parsed.data["argument-hint"] === "string" && parsed.data["argument-hint"].trim()
+						? parsed.data["argument-hint"].trim()
+						: undefined
 				commandContent = parsed.content.trim()
 			} catch (frontmatterError) {
 				// If frontmatter parsing fails, treat the entire content as command content
 				description = undefined
+				argumentHint = undefined
 				commandContent = content.trim()
 			}
 
@@ -92,6 +99,7 @@ async function tryLoadCommand(
 				source,
 				filePath,
 				description,
+				argumentHint,
 			}
 		} catch (error) {
 			// File doesn't exist or can't be read
@@ -137,6 +145,7 @@ async function scanCommandDirectory(
 
 					let parsed
 					let description: string | undefined
+					let argumentHint: string | undefined
 					let commandContent: string
 
 					try {
@@ -146,10 +155,15 @@ async function scanCommandDirectory(
 							typeof parsed.data.description === "string" && parsed.data.description.trim()
 								? parsed.data.description.trim()
 								: undefined
+						argumentHint =
+							typeof parsed.data["argument-hint"] === "string" && parsed.data["argument-hint"].trim()
+								? parsed.data["argument-hint"].trim()
+								: undefined
 						commandContent = parsed.content.trim()
 					} catch (frontmatterError) {
 						// If frontmatter parsing fails, treat the entire content as command content
 						description = undefined
+						argumentHint = undefined
 						commandContent = content.trim()
 					}
 
@@ -161,6 +175,7 @@ async function scanCommandDirectory(
 							source,
 							filePath,
 							description,
+							argumentHint,
 						})
 					}
 				} catch (error) {

src/shared/ExtensionMessage.ts

@@ -25,6 +25,7 @@ export interface Command {
 	source: "global" | "project"
 	filePath?: string
 	description?: string
+	argumentHint?: string
 }
 
 // Type for marketplace installed metadata

webview-ui/src/__tests__/command-autocomplete.spec.ts

@@ -9,6 +9,7 @@ describe("Command Autocomplete", () => {
 		{ name: "deploy", source: "global" },
 		{ name: "test-suite", source: "project" },
 		{ name: "cleanup_old", source: "global" },
+		{ name: "release", source: "project", argumentHint: "patch | minor | major" },
 	]
 
 	const mockQueryItems = [
@@ -20,19 +21,20 @@ describe("Command Autocomplete", () => {
 		it('should return all commands when query is just "/"', () => {
 			const options = getContextMenuOptions("/", null, mockQueryItems, [], [], mockCommands)
 
-			// Should have 6 items: 1 section header + 5 commands
-			expect(options).toHaveLength(6)
+			// Should have 7 items: 1 section header + 6 commands
+			expect(options).toHaveLength(7)
 
 			// Filter out section headers to check commands
 			const commandOptions = options.filter((option) => option.type === ContextMenuOptionType.Command)
-			expect(commandOptions).toHaveLength(5)
+			expect(commandOptions).toHaveLength(6)
 
 			const commandNames = commandOptions.map((option) => option.value)
 			expect(commandNames).toContain("setup")
 			expect(commandNames).toContain("build")
 			expect(commandNames).toContain("deploy")
 			expect(commandNames).toContain("test-suite")
 			expect(commandNames).toContain("cleanup_old")
+			expect(commandNames).toContain("release")
 		})
 
 		it("should filter commands based on fuzzy search", () => {
@@ -148,7 +150,7 @@ describe("Command Autocomplete", () => {
 			const commandOptions = options.filter((option) => option.type === ContextMenuOptionType.Command)
 
 			expect(modeOptions.length).toBe(2)
-			expect(commandOptions.length).toBe(5)
+			expect(commandOptions.length).toBe(6)
 		})
 
 		it("should filter both modes and commands based on query", () => {
@@ -181,6 +183,42 @@ describe("Command Autocomplete", () => {
 		})
 	})
 
+	describe("argument hint functionality", () => {
+		it("should include argumentHint in command options when present", () => {
+			const options = getContextMenuOptions("/release", null, mockQueryItems, [], [], mockCommands)
+
+			const releaseOption = options.find((option) => option.value === "release")
+			expect(releaseOption).toBeDefined()
+			expect(releaseOption!.argumentHint).toBe("patch | minor | major")
+		})
+
+		it("should handle commands without argumentHint", () => {
+			const options = getContextMenuOptions("/setup", null, mockQueryItems, [], [], mockCommands)
+
+			const setupOption = options.find((option) => option.value === "setup")
+			expect(setupOption).toBeDefined()
+			expect(setupOption!.argumentHint).toBeUndefined()
+		})
+
+		it("should preserve argumentHint through fuzzy search", () => {
+			const options = getContextMenuOptions("/rel", null, mockQueryItems, [], [], mockCommands)
+
+			const releaseOption = options.find((option) => option.value === "release")
+			expect(releaseOption).toBeDefined()
+			expect(releaseOption!.argumentHint).toBe("patch | minor | major")
+		})
+
+		it("should handle commands with empty argumentHint", () => {
+			const commandsWithEmptyHint: Command[] = [{ name: "test-command", source: "project", argumentHint: "" }]
+
+			const options = getContextMenuOptions("/test", null, mockQueryItems, [], [], commandsWithEmptyHint)
+
+			const testOption = options.find((option) => option.value === "test-command")
+			expect(testOption).toBeDefined()
+			expect(testOption!.argumentHint).toBe("")
+		})
+	})
+
 	describe("edge cases", () => {
 		it("should handle undefined commands gracefully", () => {
 			const options = getContextMenuOptions("/setup", null, mockQueryItems, [], [], undefined)