feat(console): add context-aware help with topic and payload guidance

Author: 404tk

runner/console/completer.go

@@ -54,61 +54,103 @@ var opt = []prompt.Suggest{
 }
 
 func Complete(d prompt.Document) []prompt.Suggest {
-	args := strings.Split(d.TextBeforeCursor(), " ")
+	args := completionArgs(d)
+	word := d.GetWordBeforeCursor()
 	if len(args) <= 1 {
-		return prompt.FilterHasPrefix(core, d.GetWordBeforeCursor(), true)
+		return prompt.FilterHasPrefix(core, word, true)
 	}
 	switch args[0] {
+	case "help":
+		return helpSuggestions(args, word)
 	case "use":
 		if len(args) == 2 {
-			return prompt.FilterContains(modules, d.GetWordBeforeCursor(), true)
+			return prompt.FilterContains(modules, word, true)
 		}
 	}
 	return []prompt.Suggest{}
 }
 
 func actionCompleter(d prompt.Document) []prompt.Suggest {
-	args := strings.Split(d.TextBeforeCursor(), " ")
+	args := completionArgs(d)
+	word := d.GetWordBeforeCursor()
 	if len(args) <= 1 {
-		return prompt.FilterHasPrefix(append(core, action...), d.GetWordBeforeCursor(), true)
+		return prompt.FilterHasPrefix(append(core, action...), word, true)
 	}
 	switch args[0] {
+	case "help":
+		return helpSuggestions(args, word)
 	case "use":
 		if len(args) == 2 {
-			return prompt.FilterContains(modules, d.GetWordBeforeCursor(), true)
+			return prompt.FilterContains(modules, word, true)
 		}
 	case "show":
 		if len(args) == 2 {
-			return prompt.FilterContains(opt, d.GetWordBeforeCursor(), true)
+			return prompt.FilterContains(opt, word, true)
 		}
 	case "set":
 		if len(args) == 2 {
-			getOpt := func() (p []prompt.Suggest) {
-				for k := range config {
-					if v, ok := optionsDesc[k]; ok { // && k != utils.Provider
-						p = append(p, prompt.Suggest{Text: k, Description: v})
-					}
-				}
-				return
-			}()
-			return prompt.FilterContains(getOpt, d.GetWordBeforeCursor(), true)
+			return prompt.FilterContains(optionSuggestions(), word, true)
 		}
 		if len(args) == 3 && args[1] == utils.Payload {
-			getPayloads := func() (p []prompt.Suggest) {
-				for _, entry := range payloads.Visible() {
-					p = append(p, prompt.Suggest{Text: entry.Name, Description: entry.Payload.Desc()})
-				}
-				return
-			}()
-			return prompt.FilterContains(getPayloads, d.GetWordBeforeCursor(), true)
+			return prompt.FilterContains(payloadSuggestions(), word, true)
 		}
 		if len(args) == 3 && args[1] == utils.Version {
 			var versions = []prompt.Suggest{
 				{Text: "Intl", Description: "International Edition"},
 				{Text: "China", Description: "Chinese Edition"},
 			}
-			return prompt.FilterContains(versions, d.GetWordBeforeCursor(), true)
+			return prompt.FilterContains(versions, word, true)
 		}
 	}
 	return []prompt.Suggest{}
 }
+
+func completionArgs(d prompt.Document) []string {
+	text := d.TextBeforeCursor()
+	args := strings.Fields(text)
+	if strings.HasSuffix(text, " ") || strings.HasSuffix(text, "\t") {
+		args = append(args, "")
+	}
+	return args
+}
+
+func helpSuggestions(args []string, word string) []prompt.Suggest {
+	if len(args) == 2 {
+		return prompt.FilterContains(helpTopicSuggestions(), word, true)
+	}
+	if len(args) == 3 && (args[1] == "payload" || args[1] == "metadata") {
+		return prompt.FilterContains(payloadSuggestions(), word, true)
+	}
+	return []prompt.Suggest{}
+}
+
+func helpTopicSuggestions() []prompt.Suggest {
+	suggestions := make([]prompt.Suggest, 0, len(helpTopicOrder))
+	for _, key := range helpTopicOrder {
+		if topic, ok := helpTopics[key]; ok {
+			suggestions = append(suggestions, prompt.Suggest{
+				Text:        key,
+				Description: topic.Summary,
+			})
+		}
+	}
+	return suggestions
+}
+
+func optionSuggestions() []prompt.Suggest {
+	suggestions := make([]prompt.Suggest, 0, len(config))
+	for k := range config {
+		if v, ok := optionsDesc[k]; ok {
+			suggestions = append(suggestions, prompt.Suggest{Text: k, Description: v})
+		}
+	}
+	return suggestions
+}
+
+func payloadSuggestions() []prompt.Suggest {
+	suggestions := make([]prompt.Suggest, 0, len(payloads.Visible()))
+	for _, entry := range payloads.Visible() {
+		suggestions = append(suggestions, prompt.Suggest{Text: entry.Name, Description: entry.Payload.Desc()})
+	}
+	return suggestions
+}

runner/console/executor.go

@@ -39,7 +39,7 @@ func Executor(s string) {
 		case "note":
 			note(args)
 		case "help":
-			help()
+			help(args)
 		case "clear":
 			os.Stdout.Write([]byte("\033[2J\033[H"))
 		case "exit", "quit":

runner/console/help.go

@@ -1,54 +1,51 @@
 package console
 
-import "fmt"
-
-func help() {
-	document := `
-Core Commands
-=============
-
-	Command       Description
-	-------       -----------
-	help          Help menu
-	use           Interact with a provider by name
-	sessions      List cache credential and display information about credentials
-	clear         Clear screen
-	exit          Exit the console
-
-
-Module Commands
-===============
-
-	Command       Description
-	-------       -----------
-	show          Displays provider options or validation payloads
-	set           Sets a provider option or payload parameter
-	run           Runs the selected validation workflow
-	shell         Opens an authorized instance-cmd-check session
-
-
-### Examples
-
-Select a cloud provider:
-
-	use aws
-
-Displays the options required by the provider:
-
-	show options
-
-Display the available validation payloads:
-
-	show payloads
-
-Select a validation payload:
-
-	set payload iam-user-check
-
-Select a cache credential:
-
-	sessions -i 1
+import (
+	"fmt"
+	"strings"
+)
+
+func help(args []string) {
+	args = normalizeHelpArgs(args)
+	ctx := currentHelpContext()
+	if len(args) == 0 {
+		renderContextHelp(ctx)
+		return
+	}
+
+	switch args[0] {
+	case "payload":
+		if len(args) == 1 {
+			renderPayloadCatalogHelp(ctx)
+			return
+		}
+		renderPayloadHelp(ctx, args[1], false)
+		return
+	case "metadata":
+		if len(args) == 1 {
+			renderMetadataOverviewHelp(ctx)
+			return
+		}
+		renderPayloadHelp(ctx, args[1], true)
+		return
+	}
+
+	if topic, ok := helpTopics[args[0]]; ok {
+		renderTopicHelp(ctx, topic)
+		return
+	}
+
+	fmt.Printf("No help available for %q.\n", strings.Join(args, " "))
+	fmt.Println("Try `help`, `help payload`, or `help metadata`.")
+}
 
-Use CloudToolKit only in owned, lab, or explicitly authorized environments.`
-	fmt.Println(document)
+func normalizeHelpArgs(args []string) []string {
+	normalized := make([]string, 0, len(args))
+	for _, arg := range args {
+		arg = strings.TrimSpace(arg)
+		if arg != "" {
+			normalized = append(normalized, arg)
+		}
+	}
+	return normalized
 }