Command construction and tests

// examples/cobra/cli/cli.go
package cli

import (
	"context"
	"encoding/json"
	"fmt"
	"strings"

	"github.com/spf13/cobra"
)

type List func(context.Context, string) ([]string, error)

type Tags func(context.Context) ([]string, error)

func NewRoot(list List, tags Tags) *cobra.Command {
	root := &cobra.Command{
		Use:           "catalog",
		Short:         "Browse projects",
		SilenceErrors: true, // the process boundary owns error reporting
		SilenceUsage:  true, // explicit --help still works
	}
	var asJSON bool
	root.PersistentFlags().BoolVar(&asJSON, "json", false, "Emit JSON")
	var tag string
	ls := &cobra.Command{
		Use:   "list",
		Short: "List projects",
		Args:  cobra.NoArgs,
		RunE: func(cmd *cobra.Command, _ []string) error {
			names, err := list(cmd.Context(), tag)
			if err != nil {
				return err
			}
			if names == nil {
				names = []string{}
			}
			if asJSON {
				return json.NewEncoder(cmd.OutOrStdout()).Encode(names)
			}
			for _, name := range names {
				if _, err := fmt.Fprintln(cmd.OutOrStdout(), name); err != nil {
					return err
				}
			}
			return nil
		},
	}
	ls.Flags().StringVar(&tag, "tag", "", "Filter by tag")
	// The returned error only reports a missing flag; check it anyway.
	if err := ls.RegisterFlagCompletionFunc("tag", func(cmd *cobra.Command, _ []string, prefix string) ([]string, cobra.ShellCompDirective) {
		known, err := tags(cmd.Context())
		if err != nil {
			return nil, cobra.ShellCompDirectiveError
		}
		var matches []string
		for _, t := range known {
			if strings.HasPrefix(t, prefix) {
				matches = append(matches, t)
			}
		}
		return matches, cobra.ShellCompDirectiveNoFileComp
	}); err != nil {
		panic(err) // programming error: the flag is defined above
	}
	root.AddCommand(ls)
	return root
}

// examples/cobra/cli/cmd/catalog/main.go
func main() {
	os.Exit(run(os.Args[1:], os.Stdout, os.Stderr))
}

func run(args []string, stdout, stderr io.Writer) int {
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	root := cli.NewRoot(listProjects, knownTags)
	root.Version = version
	root.SetArgs(args)
	root.SetOut(stdout)
	root.SetErr(stderr)
	if err := root.ExecuteContext(ctx); err != nil {
		if errors.Is(err, context.Canceled) {
			return exitInterrupted
		}
		fmt.Fprintln(stderr, "catalog:", err)
		return exitFailure
	}
	return exitOK
}

// examples/cobra/cli/cli_test.go
func TestListJSON(t *testing.T) {
	var out, diagnostics bytes.Buffer
	root := NewRoot(func(ctx context.Context, tag string) ([]string, error) {
		if ctx != t.Context() || tag != "go" {
			t.Fatalf("context or tag not forwarded: %q", tag)
		}
		return []string{"example"}, nil
	}, noTags)
	root.SetArgs([]string{"list", "--tag", "go", "--json"})
	root.SetOut(&out)
	root.SetErr(&diagnostics)
	if err := root.ExecuteContext(t.Context()); err != nil {
		t.Fatal(err)
	}
	var names []string
	if err := json.Unmarshal(out.Bytes(), &names); err != nil {
		t.Fatal(err)
	}
	if !slices.Equal(names, []string{"example"}) || diagnostics.Len() != 0 {
		t.Fatalf("payload=%q diagnostics=%q", out.String(), diagnostics.String())
	}
}