feat: Redesign CLI help (#3870)

* feat: redesign CLI help

* fix: test, go-lint

* fix: unit test

Author: levkohimins

cli/app.go

@@ -54,6 +54,14 @@ import (
 	"github.com/gruntwork-io/terragrunt/pkg/log/format/placeholders"
 )
 
+// Command category names.
+const (
+	MainCommandsCategoryName          = "Main commands"
+	CatalogCommandsCategoryName       = "Catalog commands"
+	ConfigurationCommandsCategoryName = "Configuration commands"
+	ShortcutsCommandsCategoryName     = "OpenTofu shortcuts"
+)
+
 func init() {
 	cli.AppVersionTemplate = AppVersionTemplate
 	cli.AppHelpTemplate = AppHelpTemplate
@@ -69,7 +77,7 @@ type App struct {
 func NewApp(opts *options.TerragruntOptions) *App {
 	app := cli.NewApp()
 	app.Name = "terragrunt"
-	app.Usage = "Terragrunt is a flexible orchestration tool that allows Infrastructure as Code written in OpenTofu/Terraform to scale. For documentation, see https://terragrunt.gruntwork.io/."
+	app.Usage = "Terragrunt is a flexible orchestration tool that allows Infrastructure as Code written in OpenTofu/Terraform to scale.\nFor documentation, see https://terragrunt.gruntwork.io/."
 	app.Author = "Gruntwork <www.gruntwork.io>"
 	app.Version = version.GetVersion()
 	app.Writer = opts.Writer
@@ -142,7 +150,7 @@ func (app *App) RunContext(ctx context.Context, args []string) error {
 	return nil
 }
 
-// GlobalFlags returns global flags. For backward compatibility, the slice contains flags that have been moved to other commands and are hidden from the CLI help,
+// GlobalFlags returns global flags. For backward compatibility, the slice contains flags that have been moved to other commands and are hidden from the CLI help.
 func GlobalFlags(opts *options.TerragruntOptions) cli.Flags {
 	globalFlags := global.NewFlags(opts, nil)
 
@@ -158,17 +166,17 @@ func GlobalFlags(opts *options.TerragruntOptions) cli.Flags {
 		graph.NewCommand(opts),              // graph
 	}
 
-	var knownFlags []string
+	var seen []string
 
 	for _, cmd := range commands {
 		for _, flag := range cmd.Flags {
 			flagName := util.FirstElement(util.RemoveEmptyElements(flag.Names()))
 
-			if slices.Contains(knownFlags, flagName) {
+			if slices.Contains(seen, flagName) {
 				continue
 			}
 
-			knownFlags = append(knownFlags, flagName)
+			seen = append(seen, flagName)
 			globalFlags = append(globalFlags, flags.NewMovedFlag(flag, cmd.Name, flags.StrictControlsByMovedGlobalFlags(opts.StrictControls, cmd.Name)))
 		}
 	}
@@ -202,30 +210,62 @@ func removeNoColorFlagDuplicates(args []string) []string {
 
 // TerragruntCommands returns the set of Terragrunt commands.
 func TerragruntCommands(opts *options.TerragruntOptions) cli.Commands {
-	cmds := cli.Commands{
-		runCmd.NewCommand(opts),             // run
-		runall.NewCommand(opts),             // runAction-all
-		terragruntinfo.NewCommand(opts),     // terragrunt-info
-		validateinputs.NewCommand(opts),     // validate-inputs
+	mainCommands := cli.Commands{
+		runall.NewCommand(opts),  // run-all
+		runCmd.NewCommand(opts),  // run
+		stack.NewCommand(opts),   // stack
+		graph.NewCommand(opts),   // graph
+		execCmd.NewCommand(opts), // exec
+	}.SetCategory(
+		&cli.Category{
+			Name:  MainCommandsCategoryName,
+			Order: 10, //nolint: mnd
+		},
+	)
+
+	catalogCommands := cli.Commands{
+		catalog.NewCommand(opts),  // catalog
+		scaffold.NewCommand(opts), // scaffold
+	}.SetCategory(
+		&cli.Category{
+			Name:  CatalogCommandsCategoryName,
+			Order: 20, //nolint: mnd
+		},
+	)
+
+	configurationCommands := cli.Commands{
 		graphdependencies.NewCommand(opts),  // graph-dependencies
-		hclfmt.NewCommand(opts),             // hclfmt
-		renderjson.NewCommand(opts),         // render-json
-		awsproviderpatch.NewCommand(opts),   // aws-provider-patch
 		outputmodulegroups.NewCommand(opts), // output-module-groups
-		catalog.NewCommand(opts),            // catalog
-		scaffold.NewCommand(opts),           // scaffold
-		stack.NewCommand(opts),              // stack
-		graph.NewCommand(opts),              // graph
+		validateinputs.NewCommand(opts),     // validate-inputs
 		hclvalidate.NewCommand(opts),        // hclvalidate
-		execCmd.NewCommand(opts),            // exec
-		helpCmd.NewCommand(opts),            // help
-		versionCmd.NewCommand(opts),         // version
+		hclfmt.NewCommand(opts),             // hclfmt
 		info.NewCommand(opts),               // info
-	}
-	cmds = append(cmds, commands.NewShortcutsCommands(opts)...)
-	cmds = append(cmds, commands.NewDeprecatedCommands(opts)...)
+		terragruntinfo.NewCommand(opts),     // terragrunt-info
+		renderjson.NewCommand(opts),         // render-json
+		helpCmd.NewCommand(opts),            // help (hidden)
+		versionCmd.NewCommand(opts),         // version (hidden)
+		awsproviderpatch.NewCommand(opts),   // aws-provider-patch (hidden)
+	}.SetCategory(
+		&cli.Category{
+			Name:  ConfigurationCommandsCategoryName,
+			Order: 30, //nolint: mnd
+		},
+	)
+
+	shortcutsCommands := commands.NewShortcutsCommands(opts).SetCategory(
+		&cli.Category{
+			Name:  ShortcutsCommandsCategoryName,
+			Order: 40, //nolint: mnd
+		},
+	)
+
+	allCommands := mainCommands.
+		Merge(catalogCommands...).
+		Merge(configurationCommands...).
+		Merge(shortcutsCommands...).
+		Merge(commands.NewDeprecatedCommands(opts)...)
 
-	return cmds
+	return allCommands
 }
 
 // WrapWithTelemetry wraps CLI command execution with setting of telemetry context and labels, if telemetry is disabled, just runAction the command.

cli/app_test.go

@@ -543,7 +543,7 @@ func TestAutocomplete(t *testing.T) { //nolint:paralleltest
 	}{
 		{
 			"",
-			[]string{"aws-provider-patch", "graph-dependencies", "hclfmt", "output-module-groups", "render-json", "run-all", "terragrunt-info", "validate-inputs"},
+			[]string{"graph-dependencies", "hclfmt", "output-module-groups", "render-json", "run-all", "terragrunt-info", "validate-inputs"},
 		},
 		{
 			"--versio",
@@ -566,7 +566,7 @@ func TestAutocomplete(t *testing.T) { //nolint:paralleltest
 		opts := options.NewTerragruntOptionsWithWriters(output, os.Stderr)
 		app := cli.NewApp(opts)
 
-		app.Commands = app.Commands.Filter([]string{"aws-provider-patch", "graph-dependencies", "hclfmt", "output-module-groups", "render-json", "run-all", "terragrunt-info", "validate-inputs"})
+		app.Commands = app.Commands.FilterByNames([]string{"graph-dependencies", "hclfmt", "output-module-groups", "render-json", "run-all", "terragrunt-info", "validate-inputs"})
 
 		err := app.Run([]string{"terragrunt"})
 		require.NoError(t, err)

cli/commands/aws-provider-patch/command.go

@@ -64,6 +64,7 @@ func NewCommand(opts *options.TerragruntOptions) *cli.Command {
 	return &cli.Command{
 		Name:   CommandName,
 		Usage:  "Overwrite settings on nested AWS providers to work around a Terraform bug (issue #13018).",
+		Hidden: true,
 		Flags:  append(run.NewFlags(opts, nil), NewFlags(opts, nil)...).Sort(),
 		Action: func(ctx *cli.Context) error { return Run(ctx, opts.OptionsFromContext(ctx)) },
 	}

cli/help.go

@@ -1,26 +1,24 @@
 package cli
 
-const AppHelpTemplate = `NAME:
-   {{$v := offset .App.HelpName 6}}{{wrap .App.HelpName 3}}{{if .App.Usage}} - {{wrap .App.Usage $v}}{{end}}
+// AppHelpTemplate is the main CLI help template.
+const AppHelpTemplate = `Usage: {{ if .App.UsageText }}{{ wrap .App.UsageText 3 }}{{ else }}{{ .App.HelpName }} [global options] <command> [options]{{ end }}{{ $description := .App.Usage }}{{ if .App.Description }}{{ $description = .App.Description }}{{ end }}{{ if $description }}
 
-USAGE:
-   {{if .App.UsageText}}{{wrap .App.UsageText 3}}{{else}}{{.App.HelpName}} <command> [options]{{end}} {{if .App.Description}}
+   {{ wrap $description 3 }}{{ end }}{{ $commands := .App.VisibleCommands }}{{ if $commands }}{{ $cv := offsetCommands $commands 5 }}
+{{ $categories := $commands.GetCategories.Sort }}{{ range $index, $category := $categories }}{{ $categoryCommands := $commands.FilterByCategory $category }}{{ if $index }}
+{{ end }}
+{{ $category.Name }}:{{ range $categoryCommands }}
+   {{ $s := .HelpName }}{{ $s }}{{ $sp := subtract $cv (offset $s 3) }}{{ indent $sp ""}} {{ wrap .Usage $cv }}{{ end }}{{ end }}{{ end }}{{ if .App.VisibleFlags }}
 
-DESCRIPTION:
-   {{wrap .App.Description 3}}{{end}}{{if .App.VisibleCommands}}
-
-COMMANDS:{{ $cv := offsetCommands .App.VisibleCommands 5}}{{range .App.VisibleCommands}}
-   {{$s := .HelpName}}{{$s}}{{ $sp := subtract $cv (offset $s 3) }}{{ indent $sp ""}} {{wrap .Usage $cv}}{{end}}{{end}}
-
-GLOBAL OPTIONS:{{if .App.VisibleFlags}}
-   {{range $index, $option := .App.VisibleFlags}}{{if $index}}
-   {{end}}{{wrap $option.String 6}}{{end}}{{end}}{{if not .App.HideVersion}}
+Global Options:
+   {{ range $index, $option := .App.VisibleFlags }}{{ if $index }}
+   {{ end }}{{ wrap $option.String 6 }}{{ end }}{{ end }}{{ if not .App.HideVersion }}
 
-VERSION: {{.App.Version}}{{if len .App.Authors}}{{end}}
+Version: {{ .App.Version }}{{ end }}{{ if len .App.Authors }}
 
-AUTHOR: {{range .App.Authors}}{{.}}{{end}} {{end}}
+Author: {{ range .App.Authors }}{{ . }}{{ end }} {{ end }}
 `
 
+// CommandHelpTemplate is the command CLI help template.
 const CommandHelpTemplate = `Usage: {{if .Command.UsageText}}{{wrap .Command.UsageText 3}}{{else}}{{range $parent := parentCommands . }}{{$parent.HelpName}} {{end}}{{.Command.HelpName}}{{if .Command.VisibleSubcommands}} <command>{{end}}{{if .Command.VisibleFlags}} [options]{{end}}{{end}}{{$description := .Command.Usage}}{{if .Command.Description}}{{$description = .Command.Description}}{{end}}{{if $description}}
 
    {{wrap $description 3}}{{end}}{{if .Command.Examples}}

internal/cli/app.go

@@ -151,7 +151,7 @@ func (app *App) VisibleFlags() Flags {
 }
 
 // VisibleCommands returns a slice of the Commands used for help.
-func (app *App) VisibleCommands() []*cli.Command {
+func (app *App) VisibleCommands() Commands {
 	if app.Commands == nil {
 		return nil
 	}

internal/cli/category.go

@@ -0,0 +1,45 @@
+package cli
+
+import "sort"
+
+// Category represents a command category used to group commands when displaying them.
+type Category struct {
+	// Name is the name of the category.
+	Name string
+	// Order is a number indicating the order in the category list.
+	Order uint
+}
+
+// String implements `fmt.Stringer` interface.
+func (category *Category) String() string {
+	return category.Name
+}
+
+// Categories is a slice of `Category`.
+type Categories []*Category
+
+// Len implements `sort.Interface` interface.
+func (categories Categories) Len() int {
+	return len(categories)
+}
+
+// Less implements `sort.Interface` interface.
+func (categories Categories) Less(i, j int) bool {
+	if categories[i].Order == categories[j].Order {
+		return categories[i].Name < categories[j].Name
+	}
+
+	return categories[i].Order < categories[j].Order
+}
+
+// Swap implements `sort.Interface` interface.
+func (categories Categories) Swap(i, j int) {
+	categories[i], categories[j] = categories[j], categories[i]
+}
+
+// Sort returns `categories` in sorted order.
+func (categories Categories) Sort() Categories {
+	sort.Sort(categories)
+
+	return categories
+}

internal/cli/command.go

@@ -4,8 +4,6 @@ import (
 	"errors"
 	libflag "flag"
 	"strings"
-
-	"github.com/urfave/cli/v2"
 )
 
 const errFlagUndefined = "flag provided but not defined:"
@@ -23,6 +21,8 @@ type Command struct {
 	Description string
 	// Examples is list of examples of using the command in the help.
 	Examples []string
+	// Category is the category the command belongs to.
+	Category *Category
 	// Flags is list of flags to parse.
 	Flags Flags
 	// ErrorOnUndefinedFlag causes the application to exit and return an error on any undefined flag.
@@ -90,7 +90,7 @@ func (cmd *Command) VisibleFlags() Flags {
 
 // VisibleSubcommands returns a slice of the Commands with Hidden=false.
 // Used by `urfave/cli` package to generate help.
-func (cmd *Command) VisibleSubcommands() []*cli.Command {
+func (cmd *Command) VisibleSubcommands() Commands {
 	if cmd.Subcommands == nil {
 		return nil
 	}

internal/cli/command_test.go

@@ -297,15 +297,15 @@ func TestCommandVisibleSubcommand(t *testing.T) {
 
 	testCases := []struct {
 		command  cli.Command
-		expected []*urfaveCli.Command
+		expected cli.Commands
 	}{
 		{
 			cli.Command{Name: "foo", Subcommands: cli.Commands{&cli.Command{Name: "bar"}, &cli.Command{Name: "baz", HelpName: "helpBaz"}}},
-			[]*urfaveCli.Command{{Name: "bar", HelpName: "bar"}, {Name: "baz", HelpName: "helpBaz"}},
+			cli.Commands{{Name: "bar", HelpName: "bar"}, {Name: "baz", HelpName: "helpBaz"}},
 		},
 		{
 			cli.Command{Name: "foo", Subcommands: cli.Commands{&cli.Command{Name: "bar", Hidden: true}, &cli.Command{Name: "baz"}}},
-			[]*urfaveCli.Command{{Name: "baz", HelpName: "baz"}},
+			cli.Commands{{Name: "baz", HelpName: "baz"}},
 		},
 	}