Move the CLI to urfave/cli v3 (closes #110)

Ported per the library's v2-to-v3 migration guide: the app is a root
cli.Command, actions take a context and the command, and flag environment
variables become value sources. -v, -q and the version flag are marked
local so that, as before, only the commands that define them accept them.
go mod tidy raises testify to v1.12.1, which v3 requires. The
urfave_cli_no_docs build tag is dropped from script/build and the
Dockerfile; v3 has no such tag. v3 no longer refuses a flag given under
two of its names, so -v --verbose now gives debug output, and the test
that pinned the refusal becomes a TestVerboseCount case. Help text follows
v3's templates.

Model: opus-5-5

internal/cli/mfer.go

@@ -1,6 +1,7 @@
 package cli
 
 import (
+	"context"
 	"errors"
 	"fmt"
 	"io"
@@ -8,7 +9,7 @@ import (
 	"time"
 
 	"github.com/spf13/afero"
-	"github.com/urfave/cli/v2"
+	"github.com/urfave/cli/v3"
 	"sneak.berlin/go/mfer/internal/log"
 	"sneak.berlin/go/mfer/mfer"
 )
@@ -54,7 +55,7 @@ type CLIApp struct {
 	gitrev      string
 	startupTime time.Time
 	exitCode    int
-	app         *cli.App
+	app         *cli.Command
 
 	Stdin  io.Reader // Standard input stream
 	Stdout io.Writer // Standard output stream for normal output
@@ -105,15 +106,15 @@ func (mfa *CLIApp) printBanner() {
 // urfave/cli reads a flag from the nearest command that defines it, so each
 // command in the lineage is asked. The highest -v count wins rather than the
 // sum, because a subcommand without its own copies reads the root's.
-func (mfa *CLIApp) setVerbosity(c *cli.Context) {
+func (mfa *CLIApp) setVerbosity(cmd *cli.Command) {
 	_, present := os.LookupEnv("MFER_DEBUG")
 
 	verbosity := 0
 	quiet := false
 
-	for _, ctx := range c.Lineage() {
-		verbosity = max(verbosity, ctx.Count("verbose"))
-		quiet = quiet || ctx.Bool("quiet")
+	for _, c := range cmd.Lineage() {
+		verbosity = max(verbosity, c.Count("verbose"))
+		quiet = quiet || c.Bool("quiet")
 	}
 
 	switch {
@@ -127,19 +128,21 @@ func (mfa *CLIApp) setVerbosity(c *cli.Context) {
 }
 
 // commonFlags returns the -v and -q flags taken by the root and by the
-// generate, check, freshen and fetch subcommands.
+// generate, check, freshen and fetch subcommands. They are local, so the
+// root's copies are not inherited by the subcommands that do not take them.
 func commonFlags() []cli.Flag {
 	return []cli.Flag{
 		&cli.BoolFlag{
 			Name:    "verbose",
 			Aliases: []string{"v"},
 			Usage:   "Increase verbosity (-v for verbose, -v -v for debug)",
-			Count:   new(int),
+			Local:   true,
 		},
 		&cli.BoolFlag{
 			Name:    "quiet",
 			Aliases: []string{"q"},
 			Usage:   "Suppress output except errors",
+			Local:   true,
 		},
 	}
 }
@@ -151,7 +154,7 @@ func requireSignatureFlag() *cli.StringFlag {
 		Name:    flagRequireSignature,
 		Aliases: []string{"S"},
 		Usage:   "Require manifest to be signed by the specified GPG key ID",
-		EnvVars: []string{"MFER_REQUIRE_SIGNATURE"},
+		Sources: cli.EnvVars("MFER_REQUIRE_SIGNATURE"),
 	}
 }
 
@@ -161,11 +164,11 @@ func (mfa *CLIApp) generateCommand() *cli.Command {
 		Aliases:   []string{"gen"},
 		Usage:     "Generate manifest file",
 		ArgsUsage: "[path ...]",
-		Action: func(c *cli.Context) error {
-			mfa.setVerbosity(c)
+		Action: func(ctx context.Context, cmd *cli.Command) error {
+			mfa.setVerbosity(cmd)
 			mfa.printBanner()
 
-			return mfa.generateManifestOperation(c)
+			return mfa.generateManifestOperation(ctx, cmd)
 		},
 		Flags: append(commonFlags(),
 			&cli.BoolFlag{
@@ -199,12 +202,12 @@ func (mfa *CLIApp) generateCommand() *cli.Command {
 				Name:    "sign-key",
 				Aliases: []string{"s"},
 				Usage:   "GPG key ID to sign the manifest with",
-				EnvVars: []string{"MFER_SIGN_KEY"},
+				Sources: cli.EnvVars("MFER_SIGN_KEY"),
 			},
 			&cli.StringFlag{
 				Name:    "seed",
 				Usage:   "Seed value for deterministic manifest UUID",
-				EnvVars: []string{"MFER_SEED"},
+				Sources: cli.EnvVars("MFER_SEED"),
 			},
 			&cli.BoolFlag{
 				Name: "include-timestamps",
@@ -220,11 +223,11 @@ func (mfa *CLIApp) checkCommand() *cli.Command {
 		Name:      cmdCheck,
 		Usage:     "Validate files using manifest file",
 		ArgsUsage: manifestArgsUsage,
-		Action: func(c *cli.Context) error {
-			mfa.setVerbosity(c)
+		Action: func(ctx context.Context, cmd *cli.Command) error {
+			mfa.setVerbosity(cmd)
 			mfa.printBanner()
 
-			return mfa.checkManifestOperation(c)
+			return mfa.checkManifestOperation(ctx, cmd)
 		},
 		Flags: append(commonFlags(),
 			&cli.StringFlag{
@@ -252,11 +255,11 @@ func (mfa *CLIApp) freshenCommand() *cli.Command {
 		Name:      cmdFreshen,
 		Usage:     "Update manifest with changed, new, and removed files",
 		ArgsUsage: manifestArgsUsage,
-		Action: func(c *cli.Context) error {
-			mfa.setVerbosity(c)
+		Action: func(ctx context.Context, cmd *cli.Command) error {
+			mfa.setVerbosity(cmd)
 			mfa.printBanner()
 
-			return mfa.freshenManifestOperation(c)
+			return mfa.freshenManifestOperation(ctx, cmd)
 		},
 		Flags: append(commonFlags(),
 			&cli.StringFlag{
@@ -285,7 +288,7 @@ func (mfa *CLIApp) freshenCommand() *cli.Command {
 				Name:    "sign-key",
 				Aliases: []string{"s"},
 				Usage:   "GPG key ID to sign the manifest with",
-				EnvVars: []string{"MFER_SIGN_KEY"},
+				Sources: cli.EnvVars("MFER_SIGN_KEY"),
 			},
 			&cli.BoolFlag{
 				Name: "include-timestamps",
@@ -301,10 +304,10 @@ func (mfa *CLIApp) exportCommand() *cli.Command {
 		Name:      cmdExport,
 		Usage:     "Export manifest contents as JSON",
 		ArgsUsage: "[manifest file or URL]",
-		Action: func(c *cli.Context) error {
-			mfa.setVerbosity(c)
+		Action: func(_ context.Context, cmd *cli.Command) error {
+			mfa.setVerbosity(cmd)
 
-			return mfa.exportManifestOperation(c)
+			return mfa.exportManifestOperation(cmd)
 		},
 	}
 }
@@ -313,7 +316,7 @@ func (mfa *CLIApp) versionCommand() *cli.Command {
 	return &cli.Command{
 		Name:  cmdVersion,
 		Usage: "Show version",
-		Action: func(_ *cli.Context) error {
+		Action: func(context.Context, *cli.Command) error {
 			mfa.printVersion()
 
 			return nil
@@ -327,8 +330,8 @@ func (mfa *CLIApp) listCommand() *cli.Command {
 		Aliases:   []string{"ls"},
 		Usage:     "List files in manifest",
 		ArgsUsage: manifestArgsUsage,
-		Action: func(c *cli.Context) error {
-			return mfa.listManifestOperation(c)
+		Action: func(_ context.Context, cmd *cli.Command) error {
+			return mfa.listManifestOperation(cmd)
 		},
 		Flags: []cli.Flag{
 			&cli.BoolFlag{
@@ -349,11 +352,11 @@ func (mfa *CLIApp) fetchCommand() *cli.Command {
 		Name:      cmdFetch,
 		Usage:     "fetch manifest and referenced files",
 		ArgsUsage: "URL",
-		Action: func(c *cli.Context) error {
-			mfa.setVerbosity(c)
+		Action: func(ctx context.Context, cmd *cli.Command) error {
+			mfa.setVerbosity(cmd)
 			mfa.printBanner()
 
-			return mfa.fetchManifestOperation(c)
+			return mfa.fetchManifestOperation(ctx, cmd)
 		},
 		Flags: append(commonFlags(),
 			&cli.DurationFlag{
@@ -385,38 +388,37 @@ func (mfa *CLIApp) run(args []string) {
 	log.SetOutput(mfa.Stdout, mfa.Stderr)
 	log.Init()
 
-	// -v means verbose, not version. urfave/cli's built-in version flag
-	// claims -v by default, which made "mfer -v --version" fail to parse and
-	// gave -v a different meaning at the root than on the generate, check,
-	// freshen and fetch subcommands, where it means verbose. Verbose is the
-	// more common meaning of -v in tools that offer both, so -v means verbose
-	// at the root too and the version flag takes the capital -V.
+	// -v means verbose, not version, at the root as on the generate, check,
+	// freshen and fetch subcommands: verbose is the more common meaning of -v
+	// in tools that offer both. urfave/cli's built-in version flag claims -v
+	// by default, so the version flag takes the capital -V instead.
 	// VersionFlag and VersionPrinter are urfave/cli package globals; run() is
 	// serialized in tests, so assigning them here is safe.
 	cli.VersionFlag = &cli.BoolFlag{
 		Name:    cmdVersion,
 		Aliases: []string{"V"},
 		Usage:   "print the version",
+		Local:   true,
 	}
-	cli.VersionPrinter = func(_ *cli.Context) { mfa.printVersion() }
+	cli.VersionPrinter = func(*cli.Command) { mfa.printVersion() }
 
-	mfa.app = &cli.App{
-		Name:                 mfa.appname,
-		Usage:                "Manifest generator",
-		Version:              mfa.VersionString(),
-		EnableBashCompletion: true,
-		Writer:               mfa.Stdout,
-		ErrWriter:            mfa.Stderr,
-		Flags:                commonFlags(),
-		Action: func(c *cli.Context) error {
-			if c.Args().Len() > 0 {
-				return fmt.Errorf("%w %q", errUnknownCommand, c.Args().First())
+	mfa.app = &cli.Command{
+		Name:                  mfa.appname,
+		Usage:                 "Manifest generator",
+		Version:               mfa.VersionString(),
+		EnableShellCompletion: true,
+		Writer:                mfa.Stdout,
+		ErrWriter:             mfa.Stderr,
+		Flags:                 commonFlags(),
+		Action: func(_ context.Context, cmd *cli.Command) error {
+			if cmd.Args().Len() > 0 {
+				return fmt.Errorf("%w %q", errUnknownCommand, cmd.Args().First())
 			}
 
-			mfa.setVerbosity(c)
+			mfa.setVerbosity(cmd)
 			mfa.printBanner()
 
-			return cli.ShowAppHelp(c)
+			return cli.ShowRootCommandHelp(cmd)
 		},
 		Commands: []*cli.Command{
 			mfa.generateCommand(),
@@ -431,7 +433,7 @@ func (mfa *CLIApp) run(args []string) {
 
 	mfa.app.HideVersion = false
 
-	err := mfa.app.Run(args)
+	err := mfa.app.Run(context.Background(), args)
 	if err != nil {
 		mfa.exitCode = 1