chore/cli: migrate users to urfave/cli

The command migration is moving legacy commander commands onto urfave/cli so they share the same help, flag, and dispatch behavior as newly migrated commands.

Migrate src users and its list, get, create, delete, prune, and tag subcommands to cli.Command definitions. Register both users and user in the migrated command map, and remove users from the legacy docs path so generated docs come from the migrated root command.

Test Plan:
- go test ./cmd/src
- go test ./...
- go run ./cmd/src users -h
- go run ./cmd/src user -h
- go run ./cmd/src users list -h

Author: burmudar

cmd/src/doc.go

@@ -63,7 +63,6 @@ Examples:
 			"extsvc":     &extsvcCommands,
 			"code-intel": &codeintelCommands,
 			"repos":      &reposCommands,
-			"users":      &usersCommands,
 		}
 
 		pending := out.Pending(output.Line("", output.StylePending, "Rendering Markdown..."))

cmd/src/run_migration_compat.go

@@ -25,8 +25,10 @@ var migratedCommands = map[string]*cli.Command{
 	// instead of writing lots of plumbing to handle an alias, lets just register it explicitly for now
 	"codeowner": codeownersCommand,
 	"login":     loginCommand,
-  "orgs":      orgsCommand,
+	"orgs":      orgsCommand,
 	"org":       orgsCommand,
+	"users":     usersCommand,
+	"user":      usersCommand,
 	"version":   versionCommand,
 }
 

cmd/src/users.go

@@ -1,14 +1,28 @@
 package main
 
 import (
-	"flag"
-	"fmt"
+	"github.com/sourcegraph/src-cli/internal/clicompat"
+	"github.com/urfave/cli/v3"
 )
 
-var usersCommands commander
+var usersCommand = clicompat.Wrap(&cli.Command{
+	Name:        "users",
+	Aliases:     []string{"user"},
+	Usage:       "manages users",
+	UsageText:   "src users [command options]",
+	Description: usersExamples,
+	HideVersion: true,
+	Commands: []*cli.Command{
+		usersListCommand,
+		usersGetCommand,
+		usersCreateCommand,
+		usersDeleteCommand,
+		usersPruneCommand,
+		usersTagCommand,
+	},
+})
 
-func init() {
-	usage := `'src users' is a tool that manages users on a Sourcegraph instance.
+const usersExamples = `'src users' is a tool that manages users on a Sourcegraph instance.
 
 Usage:
 
@@ -26,23 +40,6 @@ The commands are:
 Use "src users [command] -h" for more information about a command.
 `
 
-	flagSet := flag.NewFlagSet("users", flag.ExitOnError)
-	handler := func(args []string) error {
-		usersCommands.run(flagSet, "src users", usage, args)
-		return nil
-	}
-
-	// Register the command.
-	commands = append(commands, &command{
-		flagSet: flagSet,
-		aliases: []string{"user"},
-		handler: handler,
-		usageFunc: func() {
-			fmt.Println(usage)
-		},
-	})
-}
-
 const userFragment = `
 fragment UserFields on User {
     id

cmd/src/users_create.go

@@ -2,14 +2,13 @@ package main
 
 import (
 	"context"
-	"flag"
 	"fmt"
 
-	"github.com/sourcegraph/src-cli/internal/api"
+	"github.com/sourcegraph/src-cli/internal/clicompat"
+	"github.com/urfave/cli/v3"
 )
 
-func init() {
-	usage := `
+const usersCreateExamples = `
 Examples:
 
   Create a user account:
@@ -18,25 +17,36 @@ Examples:
 
 `
 
-	flagSet := flag.NewFlagSet("create", flag.ExitOnError)
-	usageFunc := func() {
-		fmt.Fprintf(flag.CommandLine.Output(), "Usage of 'src users %s':\n", flagSet.Name())
-		flagSet.PrintDefaults()
-		fmt.Println(usage)
-	}
-	var (
-		usernameFlag         = flagSet.String("username", "", `The new user's username. (required)`)
-		emailFlag            = flagSet.String("email", "", `The new user's email address. (required)`)
-		resetPasswordURLFlag = flagSet.Bool("reset-password-url", false, `Print the reset password URL to manually send to the new user.`)
-		apiFlags             = api.NewFlags(flagSet)
-	)
+var usersCreateCommand = clicompat.Wrap(&cli.Command{
+	Name:        "create",
+	Usage:       "creates a user account",
+	UsageText:   "src users create [options]",
+	Description: usersCreateExamples,
+	HideVersion: true,
+	Flags: clicompat.WithAPIFlags(
+		&cli.StringFlag{
+			Name:      "username",
+			Usage:     "The new user's username.",
+			Required:  true,
+			Validator: requiresNotEmpty("provide a username name using -username"),
+		},
+		&cli.StringFlag{
+			Name:      "email",
+			Usage:     "The new user's email address",
+			Required:  true,
+			Validator: requiresNotEmpty("provide a email name using -email"),
+		},
+		&cli.BoolFlag{
+			Name:  "reset-password-url",
+			Usage: "Print the reset password URL to manually send to the new user.",
+		},
+	),
+	Action: func(ctx context.Context, cmd *cli.Command) error {
+		username := cmd.String("username")
+		email := cmd.String("email")
+		resetPasswordURL := cmd.Bool("reset-password-url")
 
-	handler := func(args []string) error {
-		if err := flagSet.Parse(args); err != nil {
-			return err
-		}
-
-		client := cfg.apiClient(apiFlags, flagSet.Output())
+		client := cfg.apiClient(clicompat.APIFlagsFromCmd(cmd), cmd.Writer)
 
 		query := `mutation CreateUser(
   $username: String!,
@@ -56,24 +66,22 @@ Examples:
 			}
 		}
 		if ok, err := client.NewRequest(query, map[string]any{
-			"username": *usernameFlag,
-			"email":    *emailFlag,
-		}).Do(context.Background(), &result); err != nil || !ok {
+			"username": username,
+			"email":    email,
+		}).Do(ctx, &result); err != nil || !ok {
 			return err
 		}
 
-		fmt.Printf("User %q created.\n", *usernameFlag)
-		if *resetPasswordURLFlag && result.CreateUser.ResetPasswordURL != "" {
-			fmt.Println()
-			fmt.Printf("\tReset pasword URL: %s\n", result.CreateUser.ResetPasswordURL)
+		if _, err := fmt.Fprintf(cmd.Writer, "User %q created.\n", username); err != nil {
+			return err
+		}
+		if resetPasswordURL && result.CreateUser.ResetPasswordURL != "" {
+			if _, err := fmt.Fprintln(cmd.Writer); err != nil {
+				return err
+			}
+			_, err := fmt.Fprintf(cmd.Writer, "\tReset pasword URL: %s\n", result.CreateUser.ResetPasswordURL)
+			return err
 		}
 		return nil
-	}
-
-	// Register the command.
-	usersCommands = append(usersCommands, &command{
-		flagSet:   flagSet,
-		handler:   handler,
-		usageFunc: usageFunc,
-	})
-}
+	},
+})

cmd/src/users_delete.go

@@ -3,17 +3,16 @@ package main
 import (
 	"bufio"
 	"context"
-	"flag"
 	"fmt"
 	"os"
 	"strconv"
 	"strings"
 
-	"github.com/sourcegraph/src-cli/internal/api"
+	"github.com/sourcegraph/src-cli/internal/clicompat"
+	"github.com/urfave/cli/v3"
 )
 
-func init() {
-	usage := `
+const usersDeleteExamples = `
 Examples:
 
   Delete a user account by ID:
@@ -30,38 +29,38 @@ Examples:
 
 `
 
-	flagSet := flag.NewFlagSet("delete", flag.ExitOnError)
-	usageFunc := func() {
-		fmt.Fprintf(flag.CommandLine.Output(), "Usage of 'src users %s':\n", flagSet.Name())
-		flagSet.PrintDefaults()
-		fmt.Println(usage)
-	}
-	var (
-		userIDFlag = flagSet.String("id", "", `The ID of the user to delete.`)
-		apiFlags   = api.NewFlags(flagSet)
-	)
-
-	handler := func(args []string) error {
-		if err := flagSet.Parse(args); err != nil {
-			return err
-		}
-
-		client := cfg.apiClient(apiFlags, flagSet.Output())
-
-		if *userIDFlag == "" {
+var usersDeleteCommand = clicompat.Wrap(&cli.Command{
+	Name:        "delete",
+	Usage:       "deletes a user account",
+	UsageText:   "src users delete [options]",
+	Description: usersDeleteExamples,
+	HideVersion: true,
+	Flags: clicompat.WithAPIFlags(
+		&cli.StringFlag{
+			Name:  "id",
+			Usage: "The ID of the user to delete.",
+		},
+	),
+	Action: func(ctx context.Context, cmd *cli.Command) error {
+		userID := cmd.String("id")
+		client := cfg.apiClient(clicompat.APIFlagsFromCmd(cmd), cmd.Writer)
+
+		if userID == "" {
 			query := `query UsersTotalCountCountUsers { users { totalCount } }`
 
 			var result struct {
 				Users struct {
 					TotalCount int
 				}
 			}
-			ok, err := client.NewQuery(query).Do(context.Background(), &result)
+			ok, err := client.NewQuery(query).Do(ctx, &result)
 			if err != nil || !ok {
 				return err
 			}
 
-			fmt.Printf("No user ID specified. This would delete %d users.\nType in this number to confirm and hit return: ", result.Users.TotalCount)
+			if _, err := fmt.Fprintf(cmd.Writer, "No user ID specified. This would delete %d users.\nType in this number to confirm and hit return: ", result.Users.TotalCount); err != nil {
+				return err
+			}
 			reader := bufio.NewReader(os.Stdin)
 			text, err := reader.ReadString('\n')
 			if err != nil {
@@ -74,8 +73,8 @@ Examples:
 			}
 
 			if count != result.Users.TotalCount {
-				fmt.Println("Number does not match. Aborting.")
-				return nil
+				_, err := fmt.Fprintln(cmd.Writer, "Number does not match. Aborting.")
+				return err
 			}
 		}
 
@@ -93,19 +92,12 @@ Examples:
 			DeleteUser struct{}
 		}
 		if ok, err := client.NewRequest(query, map[string]any{
-			"user": *userIDFlag,
-		}).Do(context.Background(), &result); err != nil || !ok {
+			"user": userID,
+		}).Do(ctx, &result); err != nil || !ok {
 			return err
 		}
 
-		fmt.Printf("User with ID %q deleted.\n", *userIDFlag)
-		return nil
-	}
-
-	// Register the command.
-	usersCommands = append(usersCommands, &command{
-		flagSet:   flagSet,
-		handler:   handler,
-		usageFunc: usageFunc,
-	})
-}
+		_, err := fmt.Fprintf(cmd.Writer, "User with ID %q deleted.\n", userID)
+		return err
+	},
+})