Capture completion hints in command metadata

internal/cobra/flags.go

@@ -9,7 +9,7 @@ import (
 
 func interpretFlagTokens(argv []string, flags []commandmeta.Flag, aliases []commandmeta.FlagAlias) ([]string, map[string][]string, []commandmeta.FlagOccurrence, *commandmeta.Failure) {
 	canonical := make(map[string]commandmeta.Flag, len(flags)*2+2)
-	help := commandmeta.Flag{Name: "help", Short: "h", Boolean: true}
+	help := commandmeta.HelpFlag()
 	canonical["--help"] = help
 	canonical["-h"] = help
 	for _, flag := range flags {

internal/commandmeta/metadata.go

@@ -26,21 +26,45 @@ type Command struct {
 
 // Argument describes one positional input for usage rendering.
 type Argument struct {
-	Name  string
-	Usage string
-	Min   int
-	Max   int
+	Name       string
+	Usage      string
+	Min        int
+	Max        int
+	Completion CompletionHint
 }
 
 // Flag describes one local option without exposing a backend value.
 type Flag struct {
-	Name     string
-	Short    string
-	Usage    string
-	Default  string
-	Boolean  bool
-	Repeated bool
-	Required bool
+	Name       string
+	Short      string
+	Usage      string
+	Default    string
+	Boolean    bool
+	Repeated   bool
+	Required   bool
+	Completion CompletionHint
+}
+
+// CompletionKind selects the neutral value suggestion strategy.
+type CompletionKind uint8
+
+const (
+	CompletionNone CompletionKind = iota
+	CompletionChoices
+	CompletionFiles
+	CompletionDirectories
+)
+
+// CompletionChoice carries a literal value and optional description.
+type CompletionChoice struct {
+	Value       string
+	Description string
+}
+
+// CompletionHint describes value suggestions without backend types.
+type CompletionHint struct {
+	Kind    CompletionKind
+	Choices []CompletionChoice
 }
 
 var reportingFlags = [...]Flag{
@@ -50,8 +74,24 @@ var reportingFlags = [...]Flag{
 	{Name: "progress", Usage: "show progress messages", Default: "false", Boolean: true},
 }
 
+// BooleanCompletion returns the ordinary explicit boolean suggestions.
+func BooleanCompletion() CompletionHint {
+	return CompletionHint{Kind: CompletionChoices, Choices: []CompletionChoice{{Value: "true"}, {Value: "false"}}}
+}
+
+// HelpFlag describes the built-in help option for parser contexts.
+func HelpFlag() Flag {
+	return Flag{Name: "help", Short: "h", Boolean: true, Completion: BooleanCompletion()}
+}
+
 // ReportingFlags returns the flags shared by CommandKit's invocation reporter.
-func ReportingFlags() []Flag { return append([]Flag(nil), reportingFlags[:]...) }
+func ReportingFlags() []Flag {
+	flags := append([]Flag(nil), reportingFlags[:]...)
+	for index := range flags {
+		flags[index].Completion = BooleanCompletion()
+	}
+	return flags
+}
 
 // IsReportingFlag reports whether name is reserved for a shared reporting flag.
 func IsReportingFlag(name string) bool {