feat: migrate from docopt to cobra for CLI argument parsing

Replace docopt-go with spf13/cobra, giving cheat a built-in
`--completion` flag that dynamically generates shell completions for
bash, zsh, fish, and powershell. This replaces the manually-maintained
static completion scripts and resolves the root cause of multiple
completion issues (#768, #705, #633, #632, #476).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

internal/completions/cheatsheets.go

@@ -0,0 +1,43 @@
+// Package completions provides dynamic shell completion functions and
+// completion script generation for the cheat CLI.
+package completions
+
+import (
+	"sort"
+
+	"github.com/spf13/cobra"
+
+	"github.com/cheat/cheat/internal/sheets"
+)
+
+// Cheatsheets provides completion for cheatsheet names.
+func Cheatsheets(
+	_ *cobra.Command,
+	args []string,
+	_ string,
+) ([]string, cobra.ShellCompDirective) {
+
+	if len(args) > 0 {
+		return nil, cobra.ShellCompDirectiveNoFileComp
+	}
+
+	conf, err := loadConfig()
+	if err != nil {
+		return nil, cobra.ShellCompDirectiveNoFileComp
+	}
+
+	cheatsheets, err := sheets.Load(conf.Cheatpaths)
+	if err != nil {
+		return nil, cobra.ShellCompDirectiveNoFileComp
+	}
+
+	consolidated := sheets.Consolidate(cheatsheets)
+
+	names := make([]string, 0, len(consolidated))
+	for name := range consolidated {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+
+	return names, cobra.ShellCompDirectiveNoFileComp
+}

internal/completions/config.go

@@ -0,0 +1,38 @@
+package completions
+
+import (
+	"runtime"
+
+	"github.com/mitchellh/go-homedir"
+
+	"github.com/cheat/cheat/internal/config"
+)
+
+// loadConfig loads the cheat configuration for use in completion functions.
+// It returns an error rather than exiting, since completions should degrade
+// gracefully.
+func loadConfig() (config.Config, error) {
+	home, err := homedir.Dir()
+	if err != nil {
+		return config.Config{}, err
+	}
+
+	envvars := config.EnvVars()
+
+	confpaths, err := config.Paths(runtime.GOOS, home, envvars)
+	if err != nil {
+		return config.Config{}, err
+	}
+
+	confpath, err := config.Path(confpaths)
+	if err != nil {
+		return config.Config{}, err
+	}
+
+	conf, err := config.New(confpath, true)
+	if err != nil {
+		return config.Config{}, err
+	}
+
+	return conf, nil
+}

internal/completions/generate.go

@@ -0,0 +1,24 @@
+package completions
+
+import (
+	"fmt"
+	"io"
+
+	"github.com/spf13/cobra"
+)
+
+// Generate writes a shell completion script to the given writer.
+func Generate(cmd *cobra.Command, shell string, w io.Writer) error {
+	switch shell {
+	case "bash":
+		return cmd.Root().GenBashCompletionV2(w, true)
+	case "zsh":
+		return cmd.Root().GenZshCompletion(w)
+	case "fish":
+		return cmd.Root().GenFishCompletion(w, true)
+	case "powershell":
+		return cmd.Root().GenPowerShellCompletionWithDesc(w)
+	default:
+		return fmt.Errorf("unsupported shell: %s (valid: bash, zsh, fish, powershell)", shell)
+	}
+}

internal/completions/paths.go

@@ -0,0 +1,25 @@
+package completions
+
+import (
+	"github.com/spf13/cobra"
+)
+
+// Paths provides completion for the --path flag.
+func Paths(
+	_ *cobra.Command,
+	_ []string,
+	_ string,
+) ([]string, cobra.ShellCompDirective) {
+
+	conf, err := loadConfig()
+	if err != nil {
+		return nil, cobra.ShellCompDirectiveNoFileComp
+	}
+
+	names := make([]string, 0, len(conf.Cheatpaths))
+	for _, cp := range conf.Cheatpaths {
+		names = append(names, cp.Name)
+	}
+
+	return names, cobra.ShellCompDirectiveNoFileComp
+}

internal/completions/tags.go

@@ -0,0 +1,27 @@
+package completions
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/cheat/cheat/internal/sheets"
+)
+
+// Tags provides completion for the --tag flag.
+func Tags(
+	_ *cobra.Command,
+	_ []string,
+	_ string,
+) ([]string, cobra.ShellCompDirective) {
+
+	conf, err := loadConfig()
+	if err != nil {
+		return nil, cobra.ShellCompDirectiveNoFileComp
+	}
+
+	cheatsheets, err := sheets.Load(conf.Cheatpaths)
+	if err != nil {
+		return nil, cobra.ShellCompDirectiveNoFileComp
+	}
+
+	return sheets.Tags(cheatsheets), cobra.ShellCompDirectiveNoFileComp
+}