Support shell completion via carapace spec generation (#197)

* Add a completion example and some docs

* Add some more completion test cases

* Fix copy paste typo

Author: FollowTheProcess

README.md

@@ -25,6 +25,7 @@ Tiny, simple, but powerful CLI framework for modern Go 🚀
     - [Sub Commands](#sub-commands)
     - [Flags](#flags)
     - [Arguments](#arguments)
+    - [Shell Completion](#shell-completion)
   - [Core Principles](#core-principles)
     - [😱 Well behaved libraries don't panic](#-well-behaved-libraries-dont-panic)
     - [🧘🏻 Keep it Simple](#-keep-it-simple)
@@ -300,6 +301,33 @@ The types you can currently use for positional args are:
 > Slice types are not supported (yet), for those you need to use the `cmd.Args()` method to get the arguments manually. I plan to address this but it can be tricky
 > as slice types will eat up the remainder of the arguments so I need to figure out a good DevEx for this as it could lead to confusing outcomes
 
+### Shell Completion
+
+`cli` has built-in support for shell completions via [carapace-bin]. Wire in `cli.CompletionSubCommand()` alongside your other subcommands:
+
+```go
+cmd, err := cli.New(
+    "mytool",
+    // ...
+    cli.SubCommands(
+        buildServeCommand,
+        buildDeployCommand,
+        cli.CompletionSubCommand(), // add this
+    ),
+)
+```
+
+Running `mytool completion` outputs a [carapace-spec] YAML document describing your full command tree — all subcommands, flags, and descriptions. Redirect it once to register completions with [carapace-bin]:
+
+```shell
+mytool completion > ~/.config/carapace/specs/mytool.yaml
+```
+
+carapace-bin then provides completions across bash, zsh, fish, nushell, PowerShell, and more — no shell-specific scripts required.
+
+> [!TIP]
+> See the [`./examples/completion`](https://github.com/FollowTheProcess/cli/tree/main/examples/completion) example for a working demonstration, and the [carapace-spec] docs for how to extend the generated YAML with semantic completion hints (file paths, environment variables, etc.)
+
 ## Core Principles
 
 When designing and implementing `cli`, I had some core goals and guiding principles for implementation.
@@ -410,3 +438,5 @@ I built `cli` for my own uses really, so I've quickly adopted it across a number
 [spf13/pflag]: https://github.com/spf13/pflag
 [urfave/cli]: https://github.com/urfave/cli
 [functional options]: https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis
+[carapace-bin]: https://github.com/carapace-sh/carapace-bin
+[carapace-spec]: https://github.com/carapace-sh/carapace-spec

completion.go

@@ -0,0 +1,182 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+	"slices"
+	"strings"
+
+	publicflag "go.followtheprocess.codes/cli/flag"
+	"go.yaml.in/yaml/v4"
+)
+
+const completionLong = `
+Outputs a carapace-spec YAML document describing this command's flags and subcommands.
+
+Redirect the output to register completions with carapace-bin:
+
+  mytool completion > ~/.config/carapace/specs/mytool.yaml
+`
+
+// CompletionSubCommand returns a [Builder] that constructs a "completion" subcommand.
+//
+// When run, it outputs a carapace-spec YAML document to stdout describing the full
+// command tree, all flags, and all subcommands.
+//
+// Wire it into your root command:
+//
+//	cli.New("mytool",
+//	    cli.SubCommands(cli.CompletionSubCommand()),
+//	    ...
+//	)
+//
+// Users register completions by running:
+//
+//	mytool completion > ~/.config/carapace/specs/mytool.yaml
+//
+// carapace-bin then provides completions across bash, zsh, fish, nushell,
+// powershell, and more. See https://github.com/carapace-sh/carapace-spec
+// for how to extend the generated YAML with semantic completion hints.
+func CompletionSubCommand() Builder {
+	return func() (*Command, error) {
+		return New(
+			"completion",
+			Short("Output a carapace-spec YAML document to stdout"),
+			Long(completionLong),
+			Run(func(_ context.Context, cmd *Command) error {
+				data, err := marshalCompletionSpec(cmd.root())
+				if err != nil {
+					return fmt.Errorf("generating carapace spec: %w", err)
+				}
+
+				_, err = cmd.Stdout().Write(data)
+
+				return err
+			}),
+		)
+	}
+}
+
+// specCommand is the internal representation of a carapace-spec YAML command node.
+//
+// See https://github.com/carapace-sh/carapace-spec for the full schema.
+type specCommand struct {
+	Name            string            `yaml:"name"`
+	Description     string            `yaml:"description,omitempty"`
+	Flags           map[string]string `yaml:"flags,omitempty"`
+	PersistentFlags map[string]string `yaml:"persistentflags,omitempty"`
+	Commands        []specCommand     `yaml:"commands,omitempty"`
+}
+
+// marshalCompletionSpec generates a carapace-spec YAML document for cmd and its
+// full subcommand tree.
+func marshalCompletionSpec(cmd *Command) ([]byte, error) {
+	spec := buildSpecTree(cmd)
+
+	// Help and version are on every command; declare them once as persistentflags.
+	spec.PersistentFlags = persistentFlagsFrom(cmd)
+
+	data, err := yaml.Marshal(spec)
+	if err != nil {
+		return nil, fmt.Errorf("marshalling carapace spec: %w", err)
+	}
+
+	return data, nil
+}
+
+// isSystemFlag reports whether name is an automatically-injected flag.
+// These flags appear on every command and are emitted as persistentflags
+// on the root rather than repeated in every command's flags map.
+func isSystemFlag(name string) bool {
+	return name == "help" || name == "version"
+}
+
+// buildSpecTree recursively builds a specCommand tree from cmd.
+func buildSpecTree(cmd *Command) specCommand {
+	spec := specCommand{
+		Name:        cmd.name,
+		Description: cmd.short,
+		Flags:       specFlagsFrom(cmd),
+	}
+
+	if len(cmd.subcommands) > 0 {
+		sorted := make([]*Command, len(cmd.subcommands))
+		copy(sorted, cmd.subcommands)
+		slices.SortFunc(sorted, func(a, b *Command) int {
+			return strings.Compare(a.name, b.name)
+		})
+
+		spec.Commands = make([]specCommand, len(sorted))
+		for i, sub := range sorted {
+			spec.Commands[i] = buildSpecTree(sub)
+		}
+	}
+
+	return spec
+}
+
+// specFlagsFrom builds the carapace-spec flags map for cmd, excluding system
+// flags (help, version) which are emitted as persistentflags on the root.
+func specFlagsFrom(cmd *Command) map[string]string {
+	flags := make(map[string]string)
+
+	for name, fl := range cmd.flagSet().All() {
+		if isSystemFlag(name) {
+			continue
+		}
+
+		key := specFlagKey(name, fl.Short(), fl.Type(), fl.NoArgValue())
+		flags[key] = fl.Usage()
+	}
+
+	if len(flags) == 0 {
+		return nil
+	}
+
+	return flags
+}
+
+// persistentFlagsFrom builds the carapace-spec persistentflags map from the
+// system flags (help, version) that are automatically added to every command.
+func persistentFlagsFrom(cmd *Command) map[string]string {
+	flags := make(map[string]string)
+
+	for name, fl := range cmd.flagSet().All() {
+		if !isSystemFlag(name) {
+			continue
+		}
+
+		key := specFlagKey(name, fl.Short(), fl.Type(), fl.NoArgValue())
+		flags[key] = fl.Usage()
+	}
+
+	if len(flags) == 0 {
+		return nil
+	}
+
+	return flags
+}
+
+// specFlagKey encodes a flag name, shorthand, and type into a carapace-spec
+// flag map key.
+func specFlagKey(name string, short rune, typ, noArgValue string) string {
+	var base string
+	if short != publicflag.NoShortHand {
+		base = fmt.Sprintf("-%s, --%s", string(short), name)
+	} else {
+		base = "--" + name
+	}
+
+	switch {
+	case noArgValue == "":
+		// Value is required
+		return base + "="
+	case typ == "bool":
+		return base
+	case typ == "count":
+		return base + "*"
+	default:
+		// Optional value
+		return base + "?"
+	}
+}