Upgrade urfave/cli from v2 to v3 to support flexible flag placement

cmd/cmd.go

@@ -17,10 +17,11 @@
 package cmd
 
 import (
+	"context"
 	"fmt"
 	"os"
 
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli/v3"
 	"github.com/version-fox/vfox/cmd/commands"
 	"github.com/version-fox/vfox/internal"
 	"github.com/version-fox/vfox/internal/logger"
@@ -31,12 +32,12 @@ func Execute(args []string) {
 }
 
 type cmd struct {
-	app     *cli.App
+	app     *cli.Command
 	version string
 }
 
 func (c *cmd) Execute(args []string) {
-	if err := c.app.Run(args); err != nil {
+	if err := c.app.Run(context.Background(), args); err != nil {
 		fmt.Println(err)
 		os.Exit(1)
 	}
@@ -48,31 +49,31 @@ func newCmd() *cmd {
 		Name:    "version",
 		Aliases: []string{"v", "V"},
 		Usage:   "print version",
-		Action: func(ctx *cli.Context, b bool) error {
+		Action: func(ctx context.Context, cmd *cli.Command, b bool) error {
 			println(version)
 			return nil
 		},
 	}
 
-	app := &cli.App{}
-	app.EnableBashCompletion = true
+	app := &cli.Command{}
+	app.EnableShellCompletion = true
 	app.Name = "vfox"
 	app.Usage = "vfox is a tool for runtime version management."
 	app.UsageText = "vfox [command] [command options]"
 	app.Copyright = "Copyright 2025 Han Li. All rights reserved."
 	app.Version = version
 	app.Description = "vfox is a cross-platform version manager, extendable via plugins. It allows you to quickly install and switch between different environment you need via the command line."
 	app.Suggest = true
-	app.BashComplete = func(ctx *cli.Context) {
-		for _, command := range ctx.App.Commands {
-			_, _ = fmt.Fprintln(ctx.App.Writer, command.Name)
+	app.ShellComplete = func(ctx context.Context, cmd *cli.Command) {
+		for _, command := range cmd.Commands {
+			_, _ = fmt.Fprintln(cmd.Writer, command.Name)
 		}
 	}
 
 	debugFlags := &cli.BoolFlag{
 		Name:  "debug",
 		Usage: "show debug information",
-		Action: func(ctx *cli.Context, b bool) error {
+		Action: func(ctx context.Context, cmd *cli.Command, b bool) error {
 			logger.SetLevel(logger.DebugLevel)
 			return nil
 		},

cmd/commands/activate.go

@@ -17,14 +17,15 @@
 package commands
 
 import (
+	"context"
 	"fmt"
 	"os"
 	"strings"
 	"text/template"
 
 	"github.com/version-fox/vfox/internal"
 
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli/v3"
 	"github.com/version-fox/vfox/internal/env"
 	"github.com/version-fox/vfox/internal/shell"
 )
@@ -36,8 +37,8 @@ var Activate = &cli.Command{
 	Category: CategorySDK,
 }
 
-func activateCmd(ctx *cli.Context) error {
-	name := ctx.Args().First()
+func activateCmd(ctx context.Context, cmd *cli.Command) error {
+	name := cmd.Args().First()
 	if name == "" {
 		return cli.Exit("shell name is required", 1)
 	}
@@ -70,7 +71,7 @@ func activateCmd(ctx *cli.Context) error {
 	str, err := s.Activate(
 		shell.ActivateConfig{
 			SelfPath: path,
-			Args:     ctx.Args().Tail(),
+			Args:     cmd.Args().Tail(),
 		},
 	)
 	if err != nil {
@@ -87,5 +88,5 @@ func activateCmd(ctx *cli.Context) error {
 		SelfPath:   path,
 		EnvContent: exportStr,
 	}
-	return hookTemplate.Execute(ctx.App.Writer, tmpCtx)
+	return hookTemplate.Execute(cmd.Writer, tmpCtx)
 }

cmd/commands/add.go

@@ -17,10 +17,11 @@
 package commands
 
 import (
+"context"
 	"fmt"
 
 	"github.com/pterm/pterm"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli/v3"
 	"github.com/version-fox/vfox/internal"
 )
 
@@ -43,8 +44,8 @@ var Add = &cli.Command{
 }
 
 // addCmd is the command to add a plugin of sdk
-func addCmd(ctx *cli.Context) error {
-	args := ctx.Args()
+func addCmd(ctx context.Context, cmd *cli.Command) error {
+	args := cmd.Args()
 
 	manager := internal.NewSdkManager()
 	defer manager.Close()
@@ -60,8 +61,8 @@ func addCmd(ctx *cli.Context) error {
 		return nil
 	} else {
 		sdkName := args.First()
-		source := ctx.String("source")
-		alias := ctx.String("alias")
+		source := cmd.String("source")
+		alias := cmd.String("alias")
 		err := manager.Add(sdkName, source, alias)
 		if err == nil {
 			pterm.Printf("Please use `%s` to install the version you need.\n", pterm.LightBlue(fmt.Sprintf("vfox install %s@<version>", sdkName)))

cmd/commands/available.go

@@ -17,10 +17,11 @@
 package commands
 
 import (
+	"context"
 	"strings"
 
 	"github.com/pterm/pterm"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli/v3"
 	"github.com/version-fox/vfox/internal"
 )
 
@@ -31,10 +32,10 @@ var Available = &cli.Command{
 	Category: CategoryPlugin,
 }
 
-func availableCmd(ctx *cli.Context) error {
+func availableCmd(ctx context.Context, cmd *cli.Command) error {
 	manager := internal.NewSdkManager()
 	defer manager.Close()
-	//categoryName := ctx.Args().First()
+	//categoryName := cmd.Args().First()
 	available, err := manager.Available()
 	if err != nil {
 		return err

cmd/commands/cd.go

@@ -1,10 +1,11 @@
 package commands
 
 import (
+	"context"
 	"fmt"
 	"os"
 
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli/v3"
 	"github.com/version-fox/vfox/internal"
 	"github.com/version-fox/vfox/internal/env"
 	"github.com/version-fox/vfox/internal/shell"
@@ -23,19 +24,19 @@ var Cd = &cli.Command{
 	Action: cdCmd,
 }
 
-func cdCmd(ctx *cli.Context) error {
+func cdCmd(ctx context.Context, cmd *cli.Command) error {
 	var dir string
 
 	manager := internal.NewSdkManager()
-	if ctx.Args().Len() == 0 {
+	if cmd.Args().Len() == 0 {
 		dir = manager.PathMeta.HomePath
 	} else {
-		sdkName := ctx.Args().First()
+		sdkName := cmd.Args().First()
 		sdk, err := manager.LookupSdk(sdkName)
 		if err != nil {
 			return err
 		}
-		if ctx.Bool("plugin") {
+		if cmd.Bool("plugin") {
 			dir = sdk.Plugin.Path
 		} else {
 			current := sdk.Current()

cmd/commands/config.go

@@ -1,6 +1,7 @@
 package commands
 
 import (
+	"context"
 	"errors"
 	"fmt"
 	"github.com/version-fox/vfox/internal/config"
@@ -9,7 +10,7 @@ import (
 	"strings"
 	"time"
 
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli/v3"
 	"github.com/version-fox/vfox/internal"
 )
 
@@ -31,23 +32,23 @@ var Config = &cli.Command{
 	Action: configCmd,
 }
 
-func configCmd(ctx *cli.Context) error {
+func configCmd(ctx context.Context, cmd *cli.Command) error {
 	manager := internal.NewSdkManager()
 	defer manager.Close()
 	conf := reflect.ValueOf(manager.Config)
 
-	if ctx.Bool("list") {
+	if cmd.Bool("list") {
 		configList("", conf)
 		return nil
 	}
 
-	args := ctx.Args()
+	args := cmd.Args()
 	if args.Len() == 0 {
-		return ctx.App.Run([]string{"CMD", "config", "-h"})
+		return cmd.Run(ctx, []string{"CMD", "config", "-h"})
 	}
 
 	keys := strings.Split(args.First(), ".")
-	unset := ctx.Bool("unset")
+	unset := cmd.Bool("unset")
 	if !unset && args.Len() == 1 {
 		configGet(conf, keys)
 		return nil

cmd/commands/current.go

@@ -17,10 +17,11 @@
 package commands
 
 import (
+	"context"
 	"fmt"
 
 	"github.com/pterm/pterm"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli/v3"
 	"github.com/version-fox/vfox/internal"
 )
 
@@ -33,10 +34,10 @@ var Current = &cli.Command{
 	Category:  CategorySDK,
 }
 
-func currentCmd(ctx *cli.Context) error {
+func currentCmd(ctx context.Context, cmd *cli.Command) error {
 	manager := internal.NewSdkManager()
 	defer manager.Close()
-	sdkName := ctx.Args().First()
+	sdkName := cmd.Args().First()
 	if sdkName == "" {
 		allSdk, err := manager.LoadAllSdk()
 		if err != nil {

cmd/commands/env.go

@@ -17,10 +17,11 @@
 package commands
 
 import (
+	"context"
 	"encoding/json"
 	"fmt"
 
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli/v3"
 	"github.com/version-fox/vfox/internal"
 	"github.com/version-fox/vfox/internal/base"
 	"github.com/version-fox/vfox/internal/env"
@@ -55,15 +56,15 @@ var Env = &cli.Command{
 	Category: CategorySDK,
 }
 
-func envCmd(ctx *cli.Context) error {
-	if ctx.IsSet("json") {
+func envCmd(ctx context.Context, cmd *cli.Command) error {
+	if cmd.IsSet("json") {
 		return outputJSON()
-	} else if ctx.IsSet("cleanup") {
+	} else if cmd.IsSet("cleanup") {
 		return cleanTmp()
-	} else if ctx.IsSet("full") {
-		return envFlag(ctx, "full")
+	} else if cmd.IsSet("full") {
+		return envFlag(cmd, "full")
 	} else {
-		return envFlag(ctx, "cwd")
+		return envFlag(cmd, "cwd")
 	}
 }
 
@@ -114,8 +115,8 @@ func cleanTmp() error {
 	return nil
 }
 
-func envFlag(ctx *cli.Context, mode string) error {
-	shellName := ctx.String("shell")
+func envFlag(cmd *cli.Command, mode string) error {
+	shellName := cmd.String("shell")
 	if shellName == "" {
 		return cli.Exit("shell name is required", 1)
 	}