feat: improve missing argument error messages (#711)

This PR adds a custom Cobra command validator that outputs useful errors
when positional arguments are missing during command execution. For
example, such an error could look like this:
```
$ hcloud server describe   
hcloud server describe [options] <server>
                                  ^^^^^^
hcloud: expected argument server at position 1
```

Where previously it would look like this:
```
$ hcloud server describe
hcloud: accepts 1 arg(s), received 0
```

Additionally, if there are more arguments provided than necessary, the
following error message will appear:
```
$ hcloud server describe arg1 arg2
hcloud server describe [options] <server>
                                          ^
hcloud: expected exactly 1 positional argument(s), but got 2
```

This is done by parsing the `Use` property of a Cobra command with a
regular expression and then matching the corresponding missing
arguments.

Fixes #700

---------

Co-authored-by: pauhull <[email protected]>

Author: phm07

CONTRIBUTING.md

@@ -139,8 +139,30 @@ Additional Commands:
   ssh                         Spawn an SSH connection for the server
 ```
 
+### Command validation
+
+Please use the `util.Validate` method to make sure the command is validated against its usage string during runtime.
+This can be done by setting the `Args` field of the `cobra.Command` struct to `util.Validate`:
+
+```go
+cmd := &cobra.Command{
+   Use:   "my-command [options]",
+   Args:  util.Validate,
+   Run: func(cmd *cobra.Command, args []string) {
+      // ...
+   },
+}
+```
+
+If you are using base commands like `base.Cmd` or `base.ListCmd` etc., this is already done for you.
+
+**Note:** Your command usage needs to follow the [docopt](http://docopt.org/) syntax for this to work.
+If your command uses optional positional arguments or other complicated usage that necessitates to disable
+argument count checking, you use `util.ValidateLenient` instead. It will not throw an error if there are
+more arguments than expected.
+
 ### Generated files
 
-Generated files (that are created by running `go generate`) should be prefixed with `zz_`. This is to group them 
+Generated files (that are created by running `go generate`) should be prefixed with `zz_`. This is to group them
 together in the file list and to easily identify them as generated files. Also, it allows the CI to check if the
 generated files are up-to-date.

internal/cmd/all/all.go

@@ -3,14 +3,15 @@ package all
 import (
 	"github.com/spf13/cobra"
 
+	"github.com/hetznercloud/cli/internal/cmd/util"
 	"github.com/hetznercloud/cli/internal/state"
 )
 
 func NewCommand(s state.State) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:                   "all",
 		Short:                 "Commands that apply to all resources",
-		Args:                  cobra.NoArgs,
+		Args:                  util.Validate,
 		TraverseChildren:      true,
 		DisableFlagsInUseLine: true,
 	}

internal/cmd/base/cmd.go

@@ -19,7 +19,7 @@ func (gc *Cmd) CobraCommand(s state.State) *cobra.Command {
 	cmd := gc.BaseCobraCommand(s.Client())
 
 	if cmd.Args == nil {
-		cmd.Args = cobra.NoArgs
+		cmd.Args = util.Validate
 	}
 
 	cmd.TraverseChildren = true

internal/cmd/base/create.go

@@ -27,7 +27,7 @@ func (cc *CreateCmd) CobraCommand(s state.State) *cobra.Command {
 	output.AddFlag(cmd, output.OptionJSON(), output.OptionYAML())
 
 	if cmd.Args == nil {
-		cmd.Args = cobra.NoArgs
+		cmd.Args = util.Validate
 	}
 
 	cmd.TraverseChildren = true

internal/cmd/base/delete.go

@@ -3,7 +3,6 @@ package base
 import (
 	"fmt"
 	"reflect"
-	"strings"
 
 	"github.com/spf13/cobra"
 
@@ -32,9 +31,9 @@ func (dc *DeleteCmd) CobraCommand(s state.State) *cobra.Command {
 	}
 
 	cmd := &cobra.Command{
-		Use:                   fmt.Sprintf("delete %s<%s>", opts, strings.ToLower(dc.ResourceNameSingular)),
+		Use:                   fmt.Sprintf("delete %s<%s>", opts, util.ToKebabCase(dc.ResourceNameSingular)),
 		Short:                 dc.ShortDescription,
-		Args:                  cobra.ExactArgs(1),
+		Args:                  util.Validate,
 		ValidArgsFunction:     cmpl.SuggestArgs(cmpl.SuggestCandidatesF(dc.NameSuggestions(s.Client()))),
 		TraverseChildren:      true,
 		DisableFlagsInUseLine: true,

internal/cmd/base/describe.go

@@ -4,7 +4,6 @@ import (
 	"fmt"
 	"os"
 	"reflect"
-	"strings"
 
 	"github.com/spf13/cobra"
 
@@ -33,9 +32,9 @@ type DescribeCmd struct {
 // CobraCommand creates a command that can be registered with cobra.
 func (dc *DescribeCmd) CobraCommand(s state.State) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:                   fmt.Sprintf("describe [options] <%s>", strings.ToLower(dc.ResourceNameSingular)),
+		Use:                   fmt.Sprintf("describe [options] <%s>", util.ToKebabCase(dc.ResourceNameSingular)),
 		Short:                 dc.ShortDescription,
-		Args:                  cobra.ExactArgs(1),
+		Args:                  util.Validate,
 		ValidArgsFunction:     cmpl.SuggestArgs(cmpl.SuggestCandidatesF(dc.NameSuggestions(s.Client()))),
 		TraverseChildren:      true,
 		DisableFlagsInUseLine: true,

internal/cmd/base/labels.go

@@ -27,9 +27,9 @@ type LabelCmds struct {
 // AddCobraCommand creates a command that can be registered with cobra.
 func (lc *LabelCmds) AddCobraCommand(s state.State) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:                   fmt.Sprintf("add-label [--overwrite] <%s> <label>...", strings.ToLower(lc.ResourceNameSingular)),
+		Use:                   fmt.Sprintf("add-label [--overwrite] <%s> <label>...", util.ToKebabCase(lc.ResourceNameSingular)),
 		Short:                 lc.ShortDescriptionAdd,
-		Args:                  cobra.MinimumNArgs(2),
+		Args:                  util.Validate,
 		ValidArgsFunction:     cmpl.SuggestArgs(cmpl.SuggestCandidatesF(lc.NameSuggestions(s.Client()))),
 		TraverseChildren:      true,
 		DisableFlagsInUseLine: true,
@@ -89,9 +89,9 @@ func validateAddLabel(_ *cobra.Command, args []string) error {
 // RemoveCobraCommand creates a command that can be registered with cobra.
 func (lc *LabelCmds) RemoveCobraCommand(s state.State) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   fmt.Sprintf("remove-label <%s> (--all | <label>...)", strings.ToLower(lc.ResourceNameSingular)),
+		Use:   fmt.Sprintf("remove-label <%s> (--all | <label>...)", util.ToKebabCase(lc.ResourceNameSingular)),
 		Short: lc.ShortDescriptionRemove,
-		Args:  cobra.MinimumNArgs(1),
+		Args:  util.ValidateLenient,
 		ValidArgsFunction: cmpl.SuggestArgs(
 			cmpl.SuggestCandidatesF(lc.NameSuggestions(s.Client())),
 			cmpl.SuggestCandidatesCtx(func(_ *cobra.Command, args []string) []string {

internal/cmd/base/list.go

@@ -35,6 +35,7 @@ func (lc *ListCmd) CobraCommand(s state.State) *cobra.Command {
 			fmt.Sprintf("Displays a list of %s.", lc.ResourceNamePlural),
 			outputColumns,
 		),
+		Args:                  util.Validate,
 		TraverseChildren:      true,
 		DisableFlagsInUseLine: true,
 		PreRunE:               s.EnsureToken,

internal/cmd/base/set_rdns.go

@@ -4,7 +4,6 @@ import (
 	"fmt"
 	"net"
 	"reflect"
-	"strings"
 
 	"github.com/spf13/cobra"
 
@@ -28,9 +27,9 @@ type SetRdnsCmd struct {
 // CobraCommand creates a command that can be registered with cobra.
 func (rc *SetRdnsCmd) CobraCommand(s state.State) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:                   fmt.Sprintf("set-rdns [options] --hostname <hostname> <%s>", strings.ToLower(rc.ResourceNameSingular)),
+		Use:                   fmt.Sprintf("set-rdns [options] --hostname <hostname> <%s>", util.ToKebabCase(rc.ResourceNameSingular)),
 		Short:                 rc.ShortDescription,
-		Args:                  cobra.ExactArgs(1),
+		Args:                  util.Validate,
 		ValidArgsFunction:     cmpl.SuggestArgs(cmpl.SuggestCandidatesF(rc.NameSuggestions(s.Client()))),
 		TraverseChildren:      true,
 		DisableFlagsInUseLine: true,

internal/cmd/base/update.go

@@ -3,7 +3,6 @@ package base
 import (
 	"fmt"
 	"reflect"
-	"strings"
 
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
@@ -28,9 +27,9 @@ type UpdateCmd struct {
 // CobraCommand creates a command that can be registered with cobra.
 func (uc *UpdateCmd) CobraCommand(s state.State) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:                   fmt.Sprintf("update [options] <%s>", strings.ToLower(uc.ResourceNameSingular)),
+		Use:                   fmt.Sprintf("update [options] <%s>", util.ToKebabCase(uc.ResourceNameSingular)),
 		Short:                 uc.ShortDescription,
-		Args:                  cobra.ExactArgs(1),
+		Args:                  util.Validate,
 		ValidArgsFunction:     cmpl.SuggestArgs(cmpl.SuggestCandidatesF(uc.NameSuggestions(s.Client()))),
 		TraverseChildren:      true,
 		DisableFlagsInUseLine: true,