Group proxy tool commands under a Tools heading in help (#334)

Co-authored-by: linear-code[bot] <222613912+linear-code[bot]@users.noreply.github.com>

Author: gtsiolis

cmd/help_test.go

@@ -38,6 +38,31 @@ func TestRootHelpOutputTemplate(t *testing.T) {
 	assertNotContains(t, out, "\n  version ")
 }
 
+func TestRootHelpGroupsToolsSeparately(t *testing.T) {
+	out, err := executeWithArgs(t, "--help")
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+
+	assertContains(t, out, "Commands:")
+	assertContains(t, out, "Tools:")
+
+	// The proxy commands must be listed under the Tools group, not among the
+	// regular commands.
+	toolsSection := out[strings.Index(out, "Tools:"):]
+	for _, tool := range []string{"aws", "az", "cdk", "sam", "terraform"} {
+		assertContains(t, toolsSection, tool)
+	}
+
+	// Tools come after the management commands in the help output.
+	if strings.Index(out, "Commands:") > strings.Index(out, "Tools:") {
+		t.Fatalf("expected Commands group to appear before Tools group\noutput:\n%s", out)
+	}
+
+	// No commands should fall through to an ungrouped section.
+	assertNotContains(t, out, "Additional Commands:")
+}
+
 func TestSubcommandHelpUsesSubcommandUsageLine(t *testing.T) {
 	out, err := executeWithArgs(t, "start", "--help")
 	if err != nil {

cmd/root.go

@@ -34,6 +34,13 @@ import (
 // emit the same name as their canonical subcommand.
 const canonicalCommandAnnotation = "lstk.canonical"
 
+// Command group IDs used to separate the proxy "tool" commands (aws, terraform,
+// cdk, sam, az) from the rest of lstk's commands in the help output.
+const (
+	groupCommands = "commands"
+	groupTools    = "tools"
+)
+
 func NewRootCmd(cfg *env.Env, tel *telemetry.Client, logger log.Logger) *cobra.Command {
 	var firstRun bool
 	root := &cobra.Command{
@@ -69,7 +76,12 @@ func NewRootCmd(cfg *env.Env, tel *telemetry.Client, logger log.Logger) *cobra.C
 	root.Flags().Lookup("version").Usage = "Show version"
 	root.SetVersionTemplate(versionLine() + "\n")
 
-	root.AddCommand(
+	root.AddGroup(
+		&cobra.Group{ID: groupCommands, Title: "Commands:"},
+		&cobra.Group{ID: groupTools, Title: "Tools:"},
+	)
+
+	commands := []*cobra.Command{
 		newStartCmd(cfg, tel, logger),
 		newStopCmd(cfg, tel),
 		newRestartCmd(cfg, tel, logger),
@@ -82,16 +94,33 @@ func NewRootCmd(cfg *env.Env, tel *telemetry.Client, logger log.Logger) *cobra.C
 		newVolumeCmd(cfg),
 		newUpdateCmd(cfg),
 		newDocsCmd(),
+		newSnapshotCmd(cfg, tel, logger),
+		newResetCmd(cfg),
+		newSaveCmd(cfg),
+		newLoadCmd(cfg, tel, logger),
+	}
+	for _, c := range commands {
+		c.GroupID = groupCommands
+	}
+
+	// Proxy commands that forward to a wrapped tool (AWS/Azure CLI, Terraform,
+	// CDK, SAM) configured to target LocalStack.
+	tools := []*cobra.Command{
 		newAWSCmd(cfg),
 		newTerraformCmd(cfg, logger),
 		newCDKCmd(cfg, logger),
 		newSamCmd(cfg, logger),
-		newSnapshotCmd(cfg, tel, logger),
 		newAzCmd(cfg),
-		newResetCmd(cfg),
-		newSaveCmd(cfg),
-		newLoadCmd(cfg, tel, logger),
-	)
+	}
+	for _, c := range tools {
+		c.GroupID = groupTools
+	}
+
+	root.AddCommand(commands...)
+	root.AddCommand(tools...)
+
+	root.SetHelpCommandGroupID(groupCommands)
+	root.SetCompletionCommandGroupID(groupCommands)
 
 	return root
 }