Group glazed flags together in cobra help section

[wesen]

When adding all the glazed flags to normal commands, the actual relevant flags for the command get drowned out in the noise:

❯ sqleton wp ls-posts-limit --help

   ls-posts-limit - Show all WP posts, limited                                       
                                                                                     
  Show all posts and their ID                                                        
                                                                                     
  For more help, run:  sqleton help ls-posts-limit                                   
                                                                                     
  ## Usage:                                                                          
                                                                                     
   sqleton wp ls-posts-limit [flags]                                                 
                                                                                     
  ## Flags:                                                                          
                                                                                     
          --csv-separator string     CSV separator (default ",")                     
          --fields string            Fields to include in the output, default: all   
          --filter string            Fields to remove from output                    
          --flatten                  Flatten nested fields (after templating)        
      -h, --help                     help for ls-posts-limit                         
      -l, --limit int                Limit the number of posts (default 10)          
      -o, --output string            Output format (table, csv, tsv, json, yaml, sqlite)
  (default "table")                                                                  
          --output-as-objects        Output as individual objects instead of JSON array
      -f, --output-file string       Output file                                     
          --select string            Select a single field and output as a single line
          --select-template string   Output a single templated value for each row, on a
  single line                                                                        
          --sort-columns             Sort columns alphabetically (default true)      
          --table-format string      Table format (ascii, markdown, html, csv, tsv)  
  (default "ascii")                                                                  
          --template string          Go Template to use for single string            
          --template-field strings   For table output, fieldName:template to create new
  fields, or @fileName to read field templates from a yaml dictionary                
          --use-row-templates        Use row templates instead of column templates   
          --with-headers             Include headers in output (CSV, TSV) (default true)
                                                                                     
  ## Global Flags:                                                                   
                                                                                     
      -D, --database string            Database name                                 
          --dbt-profile string         Name of dbt profile to use (default: default) 
  (default "default")                                                                
          --dbt-profiles-path string   Path to dbt profiles.yml (default:            
  ~/.dbt/profiles.yml)                                                               
          --driver string              Database driver                               
          --dsn string                 Database DSN                                  
      -H, --host string                Database host                                 
      -p, --password string            Database password                             
      -P, --port int                   Database port (default 3306)                  
          --repository string          Directory with additional commands to load    
  (default ~/.sqleton/queries)                                                       
      -s, --schema string              Database schema (when applicable)             
      -t, --type string                Database type (mysql, postgres, etc.) (default
  "mysql")                                                                           
          --use-dbt-profiles           Use dbt profiles.yml to connect to databases  
      -u, --user string                Database user                                 

[wesen]

Link to cobra topic here: spf13/cobra#1327

[wesen]

See also this for command groups, just out of curiosity: spf13/cobra#1003

[wesen]

See that flags can be marked as required in groups, which is interesting: https://github.com/spf13/cobra/releases

[wesen]

Here's an actual implementation of flag groups: aquasecurity/trivy#2488

[wesen]

The implementation in trivy uses each cobra.Command to call SetUsageTemplate, and fills in the help for its flags straight in there. We could do two things, we could have each command to the same, passing in some glazed structure with the ParameterDefinitionGroups of some sort, which then also calls AddFlags, or we could have the HelpSystem UsageFunc do the lookup itself.

[wesen]

There's also the fact that we can set the Annotations of a cobra command to stuff we can use to our leisure. For example, the rendered flags help.

[wesen]

See

func GetCobraHelpUsageFuncs(hs *HelpSystem) (HelpFunc, UsageFunc) {
	helpFunc := func(c *cobra.Command, args []string) {
		qb := NewSectionQuery().
			ReturnAllTypes()

		options := &RenderOptions{
			Query:           qb,
			ShowAllSections: false,
			ShowShortTopic:  false,
			HelpCommand:     c.Root().CommandPath() + " help",
		}

		cobra.CheckErr(renderCommandHelpPage(c, options, hs))
	}

	usageFunc := func(c *cobra.Command) error {
		qb := NewSectionQuery().
			ReturnExamples()

		options := &RenderOptions{
			Query:           qb,
			ShowAllSections: false,
			ShowShortTopic:  true,
			HelpCommand:     c.Root().CommandPath() + " help",
		}
		// TODO(manuel, 2023-02-19) Here is where we would compute grouped flags
		// See #59
		return renderCommandHelpPage(c, options, hs)
	}

	return helpFunc, usageFunc
}

[wesen]

One way could be to use flagGroup:XXX annotations. I think this is actually quite a slick solutions, as it allows for the most flexibility.