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 local so, as before, only the commands defining them accept them.
Every command stops reading flags at its first argument, as v2 did.
ErrWriter is stdout so usage errors print with their help. The action's
context reaches the manifest download in check, export and list.
testify rises to v1.12.1, which v3 requires; the urfave_cli_no_docs
build tag, which v3 lacks, is dropped. v3 accepts a flag given under two
names, so -v --verbose gives debug output, and the test pinning the
refusal becomes a TestVerboseCount case.

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,23 +128,34 @@ 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,
 		},
 	}
 }
 
+// stopOnFirstArg returns the StopOnNthArg setting every command uses: flags
+// are read only before the command's first argument, and everything after it
+// is an argument, as with urfave/cli v2. So `mfer gen d -v` names a path "-v".
+func stopOnFirstArg() *int {
+	n := 1
+
+	return &n
+}
+
 // requireSignatureFlag returns the --require-signature flag taken by the
 // check and fetch subcommands.
 func requireSignatureFlag() *cli.StringFlag {
@@ -151,21 +163,22 @@ 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"),
 	}
 }
 
 func (mfa *CLIApp) generateCommand() *cli.Command {
 	return &cli.Command{
-		Name:      cmdGenerate,
-		Aliases:   []string{"gen"},
-		Usage:     "Generate manifest file",
-		ArgsUsage: "[path ...]",
-		Action: func(c *cli.Context) error {
-			mfa.setVerbosity(c)
+		Name:         cmdGenerate,
+		Aliases:      []string{"gen"},
+		Usage:        "Generate manifest file",
+		ArgsUsage:    "[path ...]",
+		StopOnNthArg: stopOnFirstArg(),
+		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 +212,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",
@@ -217,14 +230,15 @@ func (mfa *CLIApp) generateCommand() *cli.Command {
 
 func (mfa *CLIApp) checkCommand() *cli.Command {
 	return &cli.Command{
-		Name:      cmdCheck,
-		Usage:     "Validate files using manifest file",
-		ArgsUsage: manifestArgsUsage,
-		Action: func(c *cli.Context) error {
-			mfa.setVerbosity(c)
+		Name:         cmdCheck,
+		Usage:        "Validate files using manifest file",
+		ArgsUsage:    manifestArgsUsage,
+		StopOnNthArg: stopOnFirstArg(),
+		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{
@@ -249,14 +263,15 @@ func (mfa *CLIApp) checkCommand() *cli.Command {
 
 func (mfa *CLIApp) freshenCommand() *cli.Command {
 	return &cli.Command{
-		Name:      cmdFreshen,
-		Usage:     "Update manifest with changed, new, and removed files",
-		ArgsUsage: manifestArgsUsage,
-		Action: func(c *cli.Context) error {
-			mfa.setVerbosity(c)
+		Name:         cmdFreshen,
+		Usage:        "Update manifest with changed, new, and removed files",
+		ArgsUsage:    manifestArgsUsage,
+		StopOnNthArg: stopOnFirstArg(),
+		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 +300,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",
@@ -298,22 +313,24 @@ func (mfa *CLIApp) freshenCommand() *cli.Command {
 
 func (mfa *CLIApp) exportCommand() *cli.Command {
 	return &cli.Command{
-		Name:      cmdExport,
-		Usage:     "Export manifest contents as JSON",
-		ArgsUsage: "[manifest file or URL]",
-		Action: func(c *cli.Context) error {
-			mfa.setVerbosity(c)
+		Name:         cmdExport,
+		Usage:        "Export manifest contents as JSON",
+		ArgsUsage:    "[manifest file or URL]",
+		StopOnNthArg: stopOnFirstArg(),
+		Action: func(ctx context.Context, cmd *cli.Command) error {
+			mfa.setVerbosity(cmd)
 
-			return mfa.exportManifestOperation(c)
+			return mfa.exportManifestOperation(ctx, cmd)
 		},
 	}
 }
 
 func (mfa *CLIApp) versionCommand() *cli.Command {
 	return &cli.Command{
-		Name:  cmdVersion,
-		Usage: "Show version",
-		Action: func(_ *cli.Context) error {
+		Name:         cmdVersion,
+		Usage:        "Show version",
+		StopOnNthArg: stopOnFirstArg(),
+		Action: func(context.Context, *cli.Command) error {
 			mfa.printVersion()
 
 			return nil
@@ -323,13 +340,12 @@ func (mfa *CLIApp) versionCommand() *cli.Command {
 
 func (mfa *CLIApp) listCommand() *cli.Command {
 	return &cli.Command{
-		Name:      "list",
-		Aliases:   []string{"ls"},
-		Usage:     "List files in manifest",
-		ArgsUsage: manifestArgsUsage,
-		Action: func(c *cli.Context) error {
-			return mfa.listManifestOperation(c)
-		},
+		Name:         "list",
+		Aliases:      []string{"ls"},
+		Usage:        "List files in manifest",
+		ArgsUsage:    manifestArgsUsage,
+		StopOnNthArg: stopOnFirstArg(),
+		Action:       mfa.listManifestOperation,
 		Flags: []cli.Flag{
 			&cli.BoolFlag{
 				Name:    "long",
@@ -346,14 +362,15 @@ func (mfa *CLIApp) listCommand() *cli.Command {
 
 func (mfa *CLIApp) fetchCommand() *cli.Command {
 	return &cli.Command{
-		Name:      cmdFetch,
-		Usage:     "fetch manifest and referenced files",
-		ArgsUsage: "URL",
-		Action: func(c *cli.Context) error {
-			mfa.setVerbosity(c)
+		Name:         cmdFetch,
+		Usage:        "fetch manifest and referenced files",
+		ArgsUsage:    "URL",
+		StopOnNthArg: stopOnFirstArg(),
+		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 +402,40 @@ 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,
+		// v3 writes its "Incorrect Usage" line to ErrWriter; v2 wrote it to
+		// stdout, before the help, so it stays on stdout.
+		ErrWriter:    mfa.Stdout,
+		Flags:        commonFlags(),
+		StopOnNthArg: stopOnFirstArg(),
+		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 +450,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