feat: suggest common mistaken subcommands (#334)

This PR adds a way for dbc to suggest commands when the user enters a
command
that doesn't exist. It adds a hook to our argument parser's error
handler to
augment the error message with a suggestion.

I started with list -> search because I notice that users and/or AI
agents like
to hallucinate 'dbc list' and I think this will help by at least
reducing the
number of turns it takes for the agent to learn about dbc search.

We might consider a fuzzy suggestion feature (saerch -> search) like
other CLI
tools use as a follow-on to this.

Author: amoeba

cmd/dbc/main.go

@@ -19,6 +19,7 @@ import (
 	"fmt"
 	"os"
 	"slices"
+	"strings"
 
 	tea "charm.land/bubbletea/v2"
 	"charm.land/lipgloss/v2"
@@ -172,6 +173,36 @@ func formatErr(err error) string {
 	}
 }
 
+var subcommandSuggestions = map[string]string{
+	"list": "search",
+}
+
+func failSubcommandAndSuggest(p *arg.Parser, msg string, subcommand ...string) {
+	// Extract the invalid command from os.Args by scanning for the first non-flag
+	// arg
+	var invalidCmd string
+	if len(os.Args) > 1 {
+		for _, arg := range os.Args[1:] {
+			if !strings.HasPrefix(arg, "-") {
+				invalidCmd = arg
+				break
+			}
+		}
+	}
+
+	p.WriteUsageForSubcommand(os.Stdout, subcommand...)
+	fmt.Fprintf(os.Stdout, "error: %s", msg)
+
+	// Optionally add suggestion
+	if invalidCmd != "" {
+		if suggestion, ok := subcommandSuggestions[invalidCmd]; ok {
+			fmt.Fprintf(os.Stderr, ". Did you mean: dbc %s?\n", suggestion)
+		}
+	}
+
+	os.Exit(2)
+}
+
 func main() {
 	var (
 		args cmds
@@ -195,7 +226,7 @@ func main() {
 			fmt.Println(dbc.Version)
 			os.Exit(0)
 		default:
-			p.FailSubcommand(err.Error(), p.SubcommandNames()...)
+			failSubcommandAndSuggest(p, err.Error(), p.SubcommandNames()...)
 		}
 	}
 

cmd/dbc/main_test.go

@@ -134,3 +134,34 @@ func TestInstallHelpMentionsVersionConstraints(t *testing.T) {
 	require.Contains(t, out, `dbc install "mysql>=1,<2"`)
 	require.Contains(t, out, "https://docs.columnar.tech/dbc/guides/installing/#version-constraints")
 }
+
+func TestSubcommandSuggestions(t *testing.T) {
+	tests := []struct {
+		name            string
+		invalidCmd      string
+		wantSuggestion  string
+		hasSuggestion   bool
+	}{
+		{
+			name:           "list suggests search",
+			invalidCmd:     "list",
+			wantSuggestion: "search",
+			hasSuggestion:  true,
+		},
+		{
+			name:          "unknown command has no suggestion",
+			invalidCmd:    "foobar",
+			hasSuggestion: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			suggestion, ok := subcommandSuggestions[tt.invalidCmd]
+			require.Equal(t, tt.hasSuggestion, ok, "expected hasSuggestion=%v for command %q", tt.hasSuggestion, tt.invalidCmd)
+			if tt.hasSuggestion {
+				require.Equal(t, tt.wantSuggestion, suggestion, "wrong suggestion for command %q", tt.invalidCmd)
+			}
+		})
+	}
+}