chore(upgrade): urfave/cli from v2 to v3 (#8035)

urfave/cli  v2 will eventually become unmaintained, switch over to v3 which is the latest supported version.

Note: the `docs` command would be a lot of work to restore with v3 ([the package is still in alpha](https://github.com/urfave/cli-docs)) An alternative to avoid a breaking change would be to not upgrade from v2 to v3 for that reason alone.
Note: these commits were cherry-picked from https://code.forgejo.org/forgefriends/forgefriends
Note: it is best reviewed side by side with no display of whitespace changes (there are a lot of those when converting vars to func).

- a few functional changes were necessary and are noted in context in the file changes tab
- https://cli.urfave.org/migrate-v2-to-v3/ upgrade instructions were followed in the most minimal way possible
- upgrade gof3 to v3.10.8 which includes and upgrade from urfave/cli  v2 to urfave/cli  v3
- upgrade gitlab.com/gitlab-org/api/client-go v0.129.0 because it is an indirect dependency of gof3 and requires a change because of a deprecated field that otherwise triggers a lint error but nothing else otherwise
- verified that the [script](https://codeberg.org/forgejo/docs/src/branch/next/scripts/cli-docs.sh) that generates the [CLI documentation](https://codeberg.org/forgejo/docs/src/branch/next/scripts/cli-docs.sh) still works. There are cosmetic differences and the **help** subcommand is no longer advertised (although it is still supported) but the `--help` option is advertised as expected so it is fine.
- end-to-end tests [passed](https://code.forgejo.org/forgejo/end-to-end/pulls/667) (they use the Forgejo CLI to some extent)

## Checklist

The [contributor guide](https://forgejo.org/docs/next/contributor/) contains information that will be helpful to first time contributors. There also are a few [conditions for merging Pull Requests in Forgejo repositories](https://codeberg.org/forgejo/governance/src/branch/main/PullRequestsAgreement.md). You are also welcome to join the [Forgejo development chatroom](https://matrix.to/#/#forgejo-development:matrix.org).

### Tests

- I added test coverage for Go changes...
  - [ ] in their respective `*_test.go` for unit tests.
  - [ ] in the `tests/integration` directory if it involves interactions with a live Forgejo server.
- I added test coverage for JavaScript changes...
  - [ ] in `web_src/js/*.test.js` if it can be unit tested.
  - [ ] in `tests/e2e/*.test.e2e.js` if it requires interactions with a live Forgejo server (see also the [developer guide for JavaScript testing](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/tests/e2e/README.md#end-to-end-tests)).

### Documentation

- [ ] I created a pull request [to the documentation](https://codeberg.org/forgejo/docs) to explain to Forgejo users how to use this change.
- [x] I did not document these changes and I do not expect someone else to do it.

### Release notes

- [ ] I do not want this change to show in the release notes.
- [ ] I want the title to show in the release notes with a link to this pull request.
- [x] I want the content of the `release-notes/<pull request number>.md` to be be used for the release notes instead of the title.

<!--start release-notes-assistant-->

## Release notes
<!--URL:https://codeberg.org/forgejo/forgejo-->
- Breaking features
  - [PR](https://codeberg.org/forgejo/forgejo/pulls/8035): <!--number 8035 --><!--line 0 --><!--description VGhlIGBmb3JnZWpvIGRvY3NgIGNvbW1hbmQgaXMgZGVwcmVjYXRlZCBhbmQgQ0xJIGVycm9ycyBhcmUgbm93IGRpc3BsYXllZCBvbiBzdGRlcnIgaW5zdGVhZCBvZiBzdGRvdXQuIFRoZXNlIGJyZWFraW5nIGNoYW5nZXMgaGFwcGVuZWQgYmVjYXVzZSB0aGUgcGFja2FnZSB1c2VkIHRvIHBhcnNlIHRoZSBjb21tYW5kIGxpbmUgYXJndW1lbnRzIHdhcyBbdXBncmFkZWQgZnJvbSB2MiB0byB2M10oaHR0cHM6Ly9jbGkudXJmYXZlLm9yZy9taWdyYXRlLXYyLXRvLXYzLykuIEEgW3NlcGFyYXRlIHByb2plY3Qgd2FzIGluaXRpYXRlZF0oaHR0cHM6Ly9naXRodWIuY29tL3VyZmF2ZS9jbGktZG9jcykgdG8gcmUtaW1wbGVtZW50IHRoZSBgZG9jc2AgY29tbWFuZCwgYnV0IGl0IGlzIG5vdCB5ZXQgcHJvZHVjdGlvbiByZWFkeS4=-->The `forgejo docs` command is deprecated and CLI errors are now displayed on stderr instead of stdout. These breaking changes happened because the package used to parse the command line arguments was [upgraded from v2 to v3](https://cli.urfave.org/migrate-v2-to-v3/). A [separate project was initiated](https://github.com/urfave/cli-docs) to re-implement the `docs` command, but it is not yet production ready.<!--description-->
<!--end release-notes-assistant-->

Co-authored-by: limiting-factor <limiting-factor@posteo.com>
Reviewed-on: https://codeberg.org/forgejo/forgejo/pulls/8035
Reviewed-by: Gusted <gusted@noreply.codeberg.org>

cmd/main.go

@@ -14,7 +14,7 @@ import (
 	"forgejo.org/modules/log"
 	"forgejo.org/modules/setting"
 
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli/v3"
 )
 
 // cmdHelp is our own help subcommand with more information
@@ -25,18 +25,18 @@ func cmdHelp() *cli.Command {
 		Aliases:   []string{"h"},
 		Usage:     "Shows a list of commands or help for one command",
 		ArgsUsage: "[command]",
-		Action: func(c *cli.Context) (err error) {
-			lineage := c.Lineage() // The order is from child to parent: help, doctor, Gitea, {Command:nil}
+		Action: func(ctx context.Context, c *cli.Command) (err error) {
+			lineage := c.Lineage() // The order is from child to parent: help, doctor, Forgejo
 			targetCmdIdx := 0
-			if c.Command.Name == "help" {
+			if c.Name == "help" {
 				targetCmdIdx = 1
 			}
-			if lineage[targetCmdIdx+1].Command != nil {
-				err = cli.ShowCommandHelp(lineage[targetCmdIdx+1], lineage[targetCmdIdx].Command.Name)
+			if targetCmdIdx+1 < len(lineage) {
+				err = cli.ShowCommandHelp(ctx, lineage[targetCmdIdx+1], lineage[targetCmdIdx].Name)
 			} else {
 				err = cli.ShowAppHelp(c)
 			}
-			_, _ = fmt.Fprintf(c.App.Writer, `
+			_, _ = fmt.Fprintf(c.Root().Writer, `
 DEFAULT CONFIGURATION:
    AppPath:    %s
    WorkPath:   %s
@@ -77,25 +77,25 @@ func appGlobalFlags() []cli.Flag {
 	}
 }
 
-func prepareSubcommandWithConfig(command *cli.Command, globalFlags []cli.Flag) {
-	command.Flags = append(append([]cli.Flag{}, globalFlags...), command.Flags...)
+func prepareSubcommandWithConfig(command *cli.Command, globalFlags func() []cli.Flag) {
+	command.Flags = append(globalFlags(), command.Flags...)
 	command.Action = prepareWorkPathAndCustomConf(command.Action)
 	command.HideHelp = true
 	if command.Name != "help" {
-		command.Subcommands = append(command.Subcommands, cmdHelp())
+		command.Commands = append(command.Commands, cmdHelp())
 	}
-	for i := range command.Subcommands {
-		prepareSubcommandWithConfig(command.Subcommands[i], globalFlags)
+	for i := range command.Commands {
+		prepareSubcommandWithConfig(command.Commands[i], globalFlags)
 	}
 }
 
 // prepareWorkPathAndCustomConf wraps the Action to prepare the work path and custom config
 // It can't use "Before", because each level's sub-command's Before will be called one by one, so the "init" would be done multiple times
-func prepareWorkPathAndCustomConf(action cli.ActionFunc) func(ctx *cli.Context) error {
-	return func(ctx *cli.Context) error {
+func prepareWorkPathAndCustomConf(action cli.ActionFunc) func(_ context.Context, _ *cli.Command) error {
+	return func(ctx context.Context, cli *cli.Command) error {
 		var args setting.ArgWorkPathAndCustomConf
 		// from children to parent, check the global flags
-		for _, curCtx := range ctx.Lineage() {
+		for _, curCtx := range cli.Lineage() {
 			if curCtx.IsSet("work-path") && args.WorkPath == "" {
 				args.WorkPath = curCtx.String("work-path")
 			}
@@ -107,15 +107,15 @@ func prepareWorkPathAndCustomConf(action cli.ActionFunc) func(ctx *cli.Context)
 			}
 		}
 		setting.InitWorkPathAndCommonConfig(os.Getenv, args)
-		if ctx.Bool("help") || action == nil {
+		if cli.Bool("help") || action == nil {
 			// the default behavior of "urfave/cli": "nil action" means "show help"
-			return cmdHelp().Action(ctx)
+			return cmdHelp().Action(ctx, cli)
 		}
-		return action(ctx)
+		return action(ctx, cli)
 	}
 }
 
-func NewMainApp(version, versionExtra string) *cli.App {
+func NewMainApp(version, versionExtra string) *cli.Command {
 	path, err := os.Executable()
 	if err != nil {
 		panic(err)
@@ -124,7 +124,7 @@ func NewMainApp(version, versionExtra string) *cli.App {
 
 	subCmdsStandalone := make([]*cli.Command, 0, 10)
 	subCmdWithConfig := make([]*cli.Command, 0, 10)
-	globalFlags := make([]cli.Flag, 0, 10)
+	globalFlags := func() []cli.Flag { return []cli.Flag{} }
 
 	//
 	// If the executable is forgejo-cli, provide a Forgejo specific CLI
@@ -133,14 +133,16 @@ func NewMainApp(version, versionExtra string) *cli.App {
 	if executable == "forgejo-cli" {
 		subCmdsStandalone = append(subCmdsStandalone, forgejo.CmdActions(context.Background()))
 		subCmdWithConfig = append(subCmdWithConfig, forgejo.CmdF3(context.Background()))
-		globalFlags = append(globalFlags, []cli.Flag{
-			&cli.BoolFlag{
-				Name: "quiet",
-			},
-			&cli.BoolFlag{
-				Name: "verbose",
-			},
-		}...)
+		globalFlags = func() []cli.Flag {
+			return []cli.Flag{
+				&cli.BoolFlag{
+					Name: "quiet",
+				},
+				&cli.BoolFlag{
+					Name: "verbose",
+				},
+			}
+		}
 	} else {
 		//
 		// Otherwise provide a Gitea compatible CLI which includes Forgejo
@@ -149,55 +151,54 @@ func NewMainApp(version, versionExtra string) *cli.App {
 		// binary and rename it to forgejo if they want.
 		//
 		subCmdsStandalone = append(subCmdsStandalone, forgejo.CmdForgejo(context.Background()))
-		subCmdWithConfig = append(subCmdWithConfig, CmdActions)
+		subCmdWithConfig = append(subCmdWithConfig, cmdActions())
 	}
 
 	return innerNewMainApp(version, versionExtra, subCmdsStandalone, subCmdWithConfig, globalFlags)
 }
 
-func innerNewMainApp(version, versionExtra string, subCmdsStandaloneArgs, subCmdWithConfigArgs []*cli.Command, globalFlagsArgs []cli.Flag) *cli.App {
-	app := cli.NewApp()
-	app.HelpName = "forgejo"
+func innerNewMainApp(version, versionExtra string, subCmdsStandaloneArgs, subCmdWithConfigArgs []*cli.Command, globalFlagsArgs func() []cli.Flag) *cli.Command {
+	app := &cli.Command{}
 	app.Name = "Forgejo"
 	app.Usage = "Beyond coding. We forge."
 	app.Description = `By default, forgejo will start serving using the web-server with no argument, which can alternatively be run by running the subcommand "web".`
 	app.Version = version + versionExtra
-	app.EnableBashCompletion = true
+	app.EnableShellCompletion = true
 
 	// these sub-commands need to use config file
 	subCmdWithConfig := []*cli.Command{
 		cmdHelp(), // the "help" sub-command was used to show the more information for "work path" and "custom config"
-		CmdWeb,
-		CmdServ,
-		CmdHook,
-		CmdKeys,
-		CmdDump,
-		CmdAdmin,
-		CmdMigrate,
-		CmdDoctor,
-		CmdManager,
-		CmdEmbedded,
-		CmdMigrateStorage,
-		CmdDumpRepository,
-		CmdRestoreRepository,
+		cmdWeb(),
+		cmdServ(),
+		cmdHook(),
+		cmdKeys(),
+		cmdDump(),
+		cmdAdmin(),
+		cmdMigrate(),
+		cmdDoctor(),
+		cmdManager(),
+		cmdEmbedded(),
+		cmdMigrateStorage(),
+		cmdDumpRepository(),
+		cmdRestoreRepository(),
 	}
 
 	subCmdWithConfig = append(subCmdWithConfig, subCmdWithConfigArgs...)
 
 	// these sub-commands do not need the config file, and they do not depend on any path or environment variable.
 	subCmdStandalone := []*cli.Command{
-		CmdCert,
-		CmdGenerate,
-		CmdDocs,
+		cmdCert(),
+		cmdGenerate(),
 	}
 	subCmdStandalone = append(subCmdStandalone, subCmdsStandaloneArgs...)
 
-	app.DefaultCommand = CmdWeb.Name
+	app.DefaultCommand = cmdWeb().Name
 
-	globalFlags := appGlobalFlags()
-	globalFlags = append(globalFlags, globalFlagsArgs...)
+	globalFlags := func() []cli.Flag {
+		return append(appGlobalFlags(), globalFlagsArgs()...)
+	}
 	app.Flags = append(app.Flags, cli.VersionFlag)
-	app.Flags = append(app.Flags, globalFlags...)
+	app.Flags = append(app.Flags, globalFlags()...)
 	app.HideHelp = true // use our own help action to show helps (with more information like default config)
 	app.Before = PrepareConsoleLoggerLevel(log.INFO)
 	for i := range subCmdWithConfig {
@@ -210,8 +211,8 @@ func innerNewMainApp(version, versionExtra string, subCmdsStandaloneArgs, subCmd
 	return app
 }
 
-func RunMainApp(app *cli.App, args ...string) error {
-	err := app.Run(args)
+func RunMainApp(app *cli.Command, args ...string) error {
+	err := app.Run(context.Background(), args)
 	if err == nil {
 		return nil
 	}
@@ -220,7 +221,7 @@ func RunMainApp(app *cli.App, args ...string) error {
 		cli.OsExiter(1)
 		return err
 	}
-	_, _ = fmt.Fprintf(app.ErrWriter, "Command error: %v\n", err)
+	_, _ = fmt.Fprintf(app.Root().ErrWriter, "Command error: %v\n", err)
 	cli.OsExiter(1)
 	return err
 }