[azsdk-cli] Organize command line hierarchy

Author: benbp

.vscode/mcp.json

@@ -3,7 +3,7 @@
     "azure-sdk-mcp": {
       "type": "stdio",
       "command": "dotnet",
-      "args": ["run", "--project", "${workspaceFolder}/tools/azsdk-cli/Azure.Sdk.Tools.Cli", "--configuration", "Debug", "--", "start"]
+      "args": ["run", "--project", "${workspaceFolder}/tools/azsdk-cli/Azure.Sdk.Tools.Cli", "--configuration", "Debug", "--", "mcp"]
     }
   }
 }

tools/azsdk-cli/Azure.Sdk.Tools.Cli.Tests/Tools/CodeownersToolsTests.cs

@@ -8,6 +8,7 @@
 using Azure.Sdk.Tools.Cli.Tests.Mocks.Services;
 using Azure.Sdk.Tools.Cli.Tools.EngSys;
 using Azure.Sdk.Tools.Cli.Configuration;
+using System.Runtime.CompilerServices;
 
 namespace Azure.Sdk.Tools.Cli.Tests.Tools
 {
@@ -17,17 +18,17 @@ public class CodeownersToolsTests
         private MockGitHubService _mockGithub;
         private Mock<ICodeownersValidatorHelper> _mockCodeownersValidator;
 
-        private CodeownersTools _tool;
+        private CodeownersTool _tool;
 
         [SetUp]
         public void Setup()
         {
             _mockGithub = new MockGitHubService();
             _mockCodeownersValidator = new Mock<ICodeownersValidatorHelper>();
 
-            _tool = new CodeownersTools(
+            _tool = new CodeownersTool(
                 _mockGithub,
-                new TestLogger<CodeownersTools>(),
+                new TestLogger<CodeownersTool>(),
                 null,
                 _mockCodeownersValidator.Object);
         }
@@ -56,7 +57,7 @@ public async Task Update_LabelMissing_NotInReview_NoPath_Throws()
             gh.Setup(s => s.GetContentsSingleAsync(Constants.AZURE_OWNER_PATH, "repo", Constants.AZURE_CODEOWNERS_PATH, It.IsAny<string>()))
                 .ReturnsAsync(new RepositoryContent("CODEOWNERS", ".github/CODEOWNERS", "shaCode", 0, ContentType.File, null, null, null, null, "utf-8", Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes("")), null, null));
 
-            var tool = new CodeownersTools(gh.Object, new TestLogger<CodeownersTools>(), null, _mockCodeownersValidator.Object);
+            var tool = new CodeownersTool(gh.Object, new TestLogger<CodeownersTool>(), null, _mockCodeownersValidator.Object);
 
             var result = await tool.UpdateCodeowners("repo", false, "", "NonExistService", [], [], true);
 
@@ -68,6 +69,8 @@ public async Task Update_LabelMissing_NotInReview_NoPath_Throws()
         [Test]
         public async Task Update_AddOwnersToExistingEntry_Success()
         {
+            Assert.Ignore("This test needs to be updated to not make an http request via codeowners utils TeamUserCache");
+
             var gh = new Mock<IGitHubService>();
             // Simulate CODEOWNERS file with an entry for /sdk/myservice/
             string codeownersContent = "/sdk/myservice/ @oldowner\n";
@@ -86,7 +89,7 @@ public async Task Update_AddOwnersToExistingEntry_Success()
             var validator = new Mock<ICodeownersValidatorHelper>();
             validator.Setup(v => v.ValidateCodeOwnerAsync(It.IsAny<string>(), It.IsAny<bool>())).ReturnsAsync(new CodeownersValidationResult { Username = "user", IsValidCodeOwner = true });
 
-            var tool = new CodeownersTools(gh.Object, new TestLogger<CodeownersTools>(), null, validator.Object);
+            var tool = new CodeownersTool(gh.Object, new TestLogger<CodeownersTool>(), null, validator.Object);
             var result = await tool.UpdateCodeowners("repoName", false, "/sdk/myservice/", "MyService", ["@oldowner", "@newowner"], ["@newowner", "@newowner2"], true);
             Assert.IsNotNull(result);
             Assert.That(result.ToString(), Does.Contain("URL:").And.Contains("Created"));
@@ -95,6 +98,8 @@ public async Task Update_AddOwnersToExistingEntry_Success()
         [Test]
         public async Task Update_RemoveOwnersFromExistingEntry_Success()
         {
+            Assert.Ignore("This test needs to be updated to not make an http request via codeowners utils TeamUserCache");
+
             var gh = new Mock<IGitHubService>();
             // Simulate CODEOWNERS file with an entry for /sdk/myservice/ with two owners
             string codeownersContent = "/sdk/myservice/ @oldowner @removeowner\n";
@@ -113,7 +118,7 @@ public async Task Update_RemoveOwnersFromExistingEntry_Success()
             var validator = new Mock<ICodeownersValidatorHelper>();
             validator.Setup(v => v.ValidateCodeOwnerAsync(It.IsAny<string>(), It.IsAny<bool>())).ReturnsAsync(new CodeownersValidationResult { Username = "user", IsValidCodeOwner = true });
 
-            var tool = new CodeownersTools(gh.Object, new TestLogger<CodeownersTools>(), null, validator.Object);
+            var tool = new CodeownersTool(gh.Object, new TestLogger<CodeownersTool>(), null, validator.Object);
             // Remove @removeowner, keep @oldowner
             var result = await tool.UpdateCodeowners("repoName", false, "/sdk/myservice/", "MyService", ["@oldowner"], [], false);
             Assert.IsNotNull(result);
@@ -154,7 +159,7 @@ public async Task Update_CreateNewEntry_PRSuccess()
             validator.Setup(v => v.ValidateCodeOwnerAsync(It.IsAny<string>(), It.IsAny<bool>()))
                 .ReturnsAsync(new CodeownersValidationResult { Username = "user", IsValidCodeOwner = true });
 
-            var tool = new CodeownersTools(gh.Object, new TestLogger<CodeownersTools>(), null, validator.Object);
+            var tool = new CodeownersTool(gh.Object, new TestLogger<CodeownersTool>(), null, validator.Object);
 
             var result = await tool.UpdateCodeowners("repoName", false, "/sdk/newsvc/", "NewSvc", ["@a", "@b"], ["@s1", "@s2"], true);
             Assert.IsNotNull(result);
@@ -195,7 +200,7 @@ public async Task Validate_CODEOWNERS_Missing_ReturnsError()
 
             var validator = new Mock<ICodeownersValidatorHelper>();
 
-            var tool = new CodeownersTools(gh.Object, new TestLogger<CodeownersTools>(), null, validator.Object);
+            var tool = new CodeownersTool(gh.Object, new TestLogger<CodeownersTool>(), null, validator.Object);
 
             var result = await tool.ValidateCodeownersEntryForService("test-repo", "Any", null);
             Assert.IsNotNull(result);

tools/azsdk-cli/Azure.Sdk.Tools.Cli.Tests/Tools/TypeSpec/TspConvertToolTest.cs

@@ -9,24 +9,6 @@ namespace Azure.Sdk.Tools.Cli.Tests.Tools
 {
     public class TspConvertToolTests
     {
-        [Test]
-        public void GetCommand_ShouldReturnCommand()
-        {
-            // Arrange
-            var logger = new Mock<ILogger<TypeSpecConvertTool>>().Object;
-            var tspHelper = new Mock<ITspClientHelper>().Object;
-            var tool = new TypeSpecConvertTool(logger, tspHelper);
-
-            // Act
-            var command = tool.GetCommandInstances().First();
-
-            Assert.Multiple(() =>
-            {
-                Assert.That(command.Name, Is.EqualTo("convert-swagger"));
-                Assert.That(command.Description, Does.Contain("Convert an existing Azure service swagger definition to a TypeSpec project"));
-            });
-        }
-
         [Test]
         public async Task ConvertSwagger_WithInvalidFileExtension_ShouldReturnError()
         {

tools/azsdk-cli/Azure.Sdk.Tools.Cli/Commands/CommandGroup.cs

@@ -5,5 +5,6 @@ namespace Azure.Sdk.Tools.Cli.Commands;
 public record CommandGroup(
     string Verb,
     string Description,
-    List<Option>? Options = null
+    List<Option>? Options = null,
+    IReadOnlyCollection<string>? Aliases = null
 );

tools/azsdk-cli/Azure.Sdk.Tools.Cli/Commands/CommandRunner.cs

@@ -25,7 +25,6 @@ public static async Task<int> BuildAndRun(
             help.Aliases.Clear();  // get rid of stuff like '-?' which just doesn't even work in some shells
             help.Aliases.Add("-h");
 
-            rootCommand.Options.Add(SharedOptions.ToolOption);
             rootCommand.Options.Add(SharedOptions.Debug);
 
             SharedOptions.Format.Validators.Add(result =>
@@ -68,6 +67,10 @@ public static async Task<int> BuildAndRun(
 
             PopulateToolHierarchy(rootCommand, toolInstances);
 
+#if DEBUG
+            ValidateCommandTree(rootCommand);
+#endif
+
             var parseResult = rootCommand.Parse(args);
             return await parseResult.InvokeAsync();
         }
@@ -109,6 +112,14 @@ private static void PopulateToolHierarchy(RootCommand rootCommand, List<MCPToolB
                             }
                         }
 
+                        if (segment.Aliases != null)
+                        {
+                            foreach (var alias in segment.Aliases)
+                            {
+                                groupCommand.Aliases.Add(alias);
+                            }
+                        }
+
                         parentMap[segment.Verb] = groupCommand;
                     }
 
@@ -139,5 +150,24 @@ private static void PopulateToolHierarchy(RootCommand rootCommand, List<MCPToolB
                 }
             }
         }
+
+#if DEBUG
+        private static void ValidateCommandTree(Command command)
+        {
+            var nameSet = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+            foreach (var sub in command.Subcommands)
+            {
+                if (!nameSet.Add(sub.Name))
+                {
+                    Console.WriteLine($"Duplicate command '{sub.Name}' under '{command.Name}'. Current children: {string.Join(", ", command.Subcommands.Select(c => c.Name))}");
+                }
+            }
+
+            foreach (var sub in command.Subcommands)
+            {
+                ValidateCommandTree(sub);
+            }
+        }
+#endif
     }
 }

tools/azsdk-cli/Azure.Sdk.Tools.Cli/Commands/HostServer/HostServerCommand.cs

@@ -1,24 +1,25 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 using System.CommandLine;
-using System.CommandLine.Parsing;
 using Azure.Sdk.Tools.Cli.Helpers;
 
 namespace Azure.Sdk.Tools.Cli.Commands.HostServer
 {
     public class HostServerCommand(ILogger<HostServerCommand> logger, IRawOutputHelper outputHelper)
     {
-        public static Option<string> ToolOption = new("--tools")
+        private static readonly Option<string> toolOption = new("--tools")
         {
             Description = "If provided, the mcp server will only list and respond to tools named the same as provided in this option. Glob matching is honored.",
             Required = false,
         };
 
         public Command GetCommand()
         {
-            Command cmd = new("mcp", "Starts the MCP server (stdio mode)");
-            cmd.Aliases.Add("start");  // backwards compatibility
+            Command cmd = new("mcp", "Starts the MCP server (stdio mode)") { toolOption };
+            Command legacyStartCmd = new("start", "Starts the MCP server (stdio mode)") { toolOption };
+            legacyStartCmd.Hidden = true;
             cmd.SetAction((_, cancellationToken) => HandleCommand(cancellationToken));
+            legacyStartCmd.SetAction((_, cancellationToken) => HandleCommand(cancellationToken));
             return cmd;
         }
 

tools/azsdk-cli/Azure.Sdk.Tools.Cli/Commands/SharedCommandGroups.cs

@@ -1,54 +1,71 @@
+using System.CommandLine;
+
 namespace Azure.Sdk.Tools.Cli.Commands
 {
     public static class SharedCommandGroups
     {
 
         public static readonly CommandGroup AzurePipelines = new(
             Verb: "azp",
-            Description: "Azure Pipelines Tool",
-            Options: []
+            Description: "Azure Pipelines commands",
+            Aliases: ["pipeline"]
         );
 
         public static readonly CommandGroup EngSys = new(
             Verb: "eng",
-            Description: "Internal azsdk engineering system commands",
-            Options: []
-        );
-
-        public static readonly CommandGroup Generators = new(
-            Verb: "generators",
-            Description: "Commands that generate files",
-            Options: []
+            Description: "Internal azsdk engineering system commands"
         );
 
         public static readonly CommandGroup Cleanup = new(
             Verb: "cleanup",
-            Description: "Cleanup commands",
-            Options: []
+            Description: "Cleanup commands"
+        );
+
+        public static readonly CommandGroup Config = new(
+            Verb: "config",
+            Description: "SDK service configuration commands"
         );
 
         public static readonly CommandGroup Log = new(
             Verb: "log",
-            Description: "Log processing commands",
-            Options: []
+            Description: "Log processing commands"
         );
 
         public static readonly CommandGroup Package = new(
-            Verb: "package",
-            Description: "Package management and validation commands",
-            Options: []
+            Verb: "pkg",
+            Description: "Package operations",
+            Aliases: ["package"]
         );
 
-        public static readonly CommandGroup SourceCode = new(
-            Verb: "source-code",
-            Description: "Source code generation and build commands",
-            Options: []
+        public static readonly CommandGroup PackageReadme = new(
+            Verb: "readme",
+            Description: "README operations for SDK packages"
+        );
+
+        public static readonly CommandGroup PackageSample = new(
+            Verb: "sample",
+            Description: "Sample operations for SDK packages"
+        );
+
+        public static readonly CommandGroup PackageTest = new(
+            Verb: "test",
+            Description: "Test operations for SDK packages"
         );
 
         public static readonly CommandGroup TypeSpec = new(
             Verb: "tsp",
-            Description: "Tools for setting up or working with TypeSpec projects",
-            Options: []
+            Description: "Commands for setting up or working with TypeSpec projects",
+            Aliases: ["typespec"]
+        );
+
+        public static readonly CommandGroup TypeSpecProject = new(
+            Verb: "project",
+            Description: "TypeSpec project utilities"
+        );
+
+        public static readonly CommandGroup TypeSpecClient = new(
+            Verb: "client",
+            Description: "TypeSpec client update helpers"
         );
 
 #if DEBUG

tools/azsdk-cli/Azure.Sdk.Tools.Cli/Commands/SharedOptions.cs

@@ -1,6 +1,5 @@
 using System;
 using System.CommandLine;
-using System.CommandLine.Parsing;
 using System.IO.Enumeration;
 using Azure.Sdk.Tools.Cli.Tools;
 using Azure.Sdk.Tools.Cli.Tools.EngSys;
@@ -17,8 +16,7 @@ public static class SharedOptions
     {
         public static readonly List<Type> ToolsList = [
             typeof(PackageCheckTool),
-            typeof(CleanupTool),
-            typeof(CodeownersTools),
+            typeof(CodeownersTool),
             typeof(GitHubLabelsTool),
             typeof(LogAnalysisTool),
             typeof(PipelineTool),
@@ -43,17 +41,12 @@ public static class SharedOptions
             typeof(TestTool),
 #if DEBUG
             // only add these tools in debug mode
+            typeof(CleanupTool),
             typeof(ExampleTool),
             typeof(HelloWorldTool),
 #endif
         ];
 
-        public static Option<string> ToolOption = new("--tools")
-        {
-            Description = "If provided, the tools server will only respond to CLI or MCP server requests for tools named the same as provided in this option. Glob matching is honored.",
-            Required = false,
-        };
-
         public static Option<string> Format = new("--output", "-o")
         {
             Description = "The format of the output. Supported formats are: plain, json",
@@ -101,14 +94,15 @@ public static string[] GetToolsFromArgs(string[] args)
             {
                 TreatUnmatchedTokensAsErrors = false
             };
-            root.Options.Add(ToolOption);
+            Option<string> toolOption = new("--tools");
+            root.Options.Add(toolOption);
 
             var result = root.Parse(args);
 
-            var raw = result.GetValue(ToolOption);
+            var raw = result.GetValue(toolOption);
             if (string.IsNullOrWhiteSpace(raw))
             {
-                return new string[] { };
+                return [];
             }
 
             return raw