fix: skip hidden subcommands inn rendered usage texts

The usage renderer failed to respect the hidden status on subcommands.
This has been corrected. Additionally, [Hidden] has been removed from
the Documented interface and given it's own interface, [HiddenCommand],
since it's generally rare for subcommands to be hidden and adds
unecessary bloat.

Teach [Execute] to detect [ErrShowUsage], which allows a command's
lifecycle routines to trigger rendering of command usage.

A few small fixes throughout the project.

Author: brandon1024

command.go

@@ -22,7 +22,7 @@ type Command interface {
 	// rendering usage and help texts.
 	Documented
 
-	// Name returns the name of this command.
+	// Name returns the name of this command or subcommand.
 	Name() string
 }
 
@@ -113,7 +113,10 @@ type Documented interface {
 
 	// ExampleText returns motivating usage examples for your command.
 	ExampleText() string
+}
 
+// HiddenCommand is implemented by commands which are not user facing. Hidden commands are not displayed in help texts.
+type HiddenCommand interface {
 	// Hidden returns a flag indicating whether to mark this command as hidden, preventing it from being rendered in
 	// help output.
 	Hidden() bool

example_lifecycle_test.go

@@ -58,10 +58,6 @@ func (c *LifecycleCommand) ExampleText() string {
 	return LifecycleCommandExamples
 }
 
-func (c *LifecycleCommand) Hidden() bool {
-	return false
-}
-
 func ExampleRunnableLifecycle() {
 	args := []string{}
 

example_subcommands_test.go

@@ -81,10 +81,6 @@ func (c *ParentCommand) ExampleText() string {
 	return ParentCommandExamples
 }
 
-func (c *ParentCommand) Hidden() bool {
-	return false
-}
-
 func (c *ParentCommand) Subcommands() []cmder.Command {
 	return c.subcommands
 }
@@ -144,10 +140,6 @@ func (c *ChildCommand) ExampleText() string {
 	return ChildCommandExamples
 }
 
-func (c *ChildCommand) Hidden() bool {
-	return false
-}
-
 // === EXAMPLE ===
 
 func ExampleRootCommand() {

example_test.go

@@ -48,10 +48,6 @@ func (c *HelloWorldCommand) ExampleText() string {
 	return HelloWorldCommandExamples
 }
 
-func (c *HelloWorldCommand) Hidden() bool {
-	return false
-}
-
 func ExampleCommand() {
 	args := []string{"from", "cmder"}
 	cmd := &HelloWorldCommand{}

examples/hello-world/child.go

@@ -57,7 +57,3 @@ func (c *WorldCommand) HelpText() string {
 func (c *WorldCommand) ExampleText() string {
 	return WorldCommandExamples
 }
-
-func (c *WorldCommand) Hidden() bool {
-	return false
-}

examples/hello-world/parent.go

@@ -80,10 +80,6 @@ func (c *HelloCommand) ExampleText() string {
 	return HelloCommandExamples
 }
 
-func (c *HelloCommand) Hidden() bool {
-	return false
-}
-
 func (c *HelloCommand) Subcommands() []cmder.Command {
 	return c.subcommands
 }

examples/http/main.go

@@ -90,7 +90,8 @@ func (c *ServerCommand) InitializeFlags(fs *flag.FlagSet) {
 
 func (c *ServerCommand) Initialize(ctx context.Context, args []string) error {
 	if len(args) != 0 {
-		return fmt.Errorf("too many arguments: %v", args)
+		fmt.Fprintf(os.Stderr, "error: too many arguments: %v\n", args)
+		return cmder.ErrShowUsage
 	}
 
 	if !c.noAuth && c.basicAuth == "" {
@@ -161,10 +162,6 @@ func (c *ServerCommand) ExampleText() string {
 	return ServerCommandExamples
 }
 
-func (c *ServerCommand) Hidden() bool {
-	return false
-}
-
 func main() {
 	cmd := &ServerCommand{}
 

execute.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"flag"
+	"fmt"
 	"os"
 	"regexp"
 	"strings"
@@ -18,7 +19,7 @@ var (
 	// Returned when an [ExecuteOption] provided to [Execute] is illegal.
 	ErrIllegalExecuteOptions = errors.New("cmder: illegal command execution option")
 
-	// Returned when an [ExecuteOption] provided to [Execute] is illegal.
+	// Returned when failed to update flag value from environment variable.
 	ErrEnvironmentBindFailure = errors.New("cmder: failed to update flag from environment variable")
 )
 
@@ -77,6 +78,9 @@ var (
 // Whenever the user provides the '-h' or '--help' flag at the command line, [Execute] will display command usage and
 // exit. The format of the help text can be adjusted by configuring [UsageTemplate]. By default, usage information will
 // be written to stderr, but this can be adjusted by setting [UsageOutputWriter].
+//
+// If a command's [Run] routine returns [ErrShowUsage] (or an error wrapping [ErrShowUsage]), [Execute] will render
+// help text and exit with status 2.
 func Execute(ctx context.Context, cmd Command, op ...ExecuteOption) error {
 	// do some checks
 	if cmd == nil {
@@ -154,25 +158,45 @@ type command struct {
 
 // onInit calls the [RunnableLifecycle] init routine if present on c.
 func (c command) onInit(ctx context.Context) error {
+	var err error
+
 	if cmd, ok := c.Command.(RunnableLifecycle); ok {
-		return cmd.Initialize(ctx, c.args)
+		err = cmd.Initialize(ctx, c.args)
 	}
 
-	return nil
+	if errors.Is(err, ErrShowUsage) {
+		_ = usage(c)
+		os.Exit(2)
+	}
+
+	return err
 }
 
 // run calls the [Runnable] run routine of c.
 func (c command) run(ctx context.Context) error {
-	return c.Run(ctx, c.args)
+	err := c.Run(ctx, c.args)
+	if errors.Is(err, ErrShowUsage) {
+		_ = usage(c)
+		os.Exit(2)
+	}
+
+	return err
 }
 
 // onDestroy calls the [RunnableLifecycle] destroy routine if present on c.
 func (c command) onDestroy(ctx context.Context) error {
+	var err error
+
 	if cmd, ok := c.Command.(RunnableLifecycle); ok {
-		return cmd.Destroy(ctx, c.args)
+		err = cmd.Destroy(ctx, c.args)
 	}
 
-	return nil
+	if errors.Is(err, ErrShowUsage) {
+		_ = usage(c)
+		os.Exit(2)
+	}
+
+	return err
 }
 
 // buildCallStack builds a slice representing the command call stack. The first element in the slice is the root
@@ -287,7 +311,11 @@ func bindEnvironmentFlags(stack []command, cmd command, ops *ExecuteOptions) err
 
 		if value, ok := os.LookupEnv(variable); ok {
 			if err := flag.Value.Set(value); err != nil {
-				return errors.Join(ErrEnvironmentBindFailure, err)
+				return errors.Join(
+					ErrEnvironmentBindFailure,
+					fmt.Errorf("cmder: failed to set flag %s from variable %s", flag.Name, variable),
+					err,
+				)
 			}
 		}
 	}

execute_test.go

@@ -3,8 +3,6 @@ package cmder
 import (
 	"context"
 	"flag"
-	"fmt"
-	"slices"
 	"testing"
 )
 
@@ -89,26 +87,3 @@ func TestExecute(t *testing.T) {
 		})
 	})
 }
-
-type result struct {
-	res bool
-	msg string
-}
-
-func assert(t *testing.T, res result) {
-	if !res.res {
-		t.Fatalf("expectation failed: %s", res.msg)
-	}
-}
-
-func eq[T comparable](expected, actual T) result {
-	return result{expected == actual, fmt.Sprintf("values not equal: expected %v but was %v", expected, actual)}
-}
-
-func nilerr(err error) result {
-	return result{err == nil, fmt.Sprintf("unexpected error: %v", err)}
-}
-
-func match[S ~[]E, E comparable](expected, actual S) result {
-	return result{slices.Equal(expected, actual), fmt.Sprintf("slices not equal: expected %v but was %v", expected, actual)}
-}

testutils_test.go

@@ -0,0 +1,36 @@
+package cmder
+
+import (
+	"fmt"
+	"slices"
+	"testing"
+)
+
+// result represents the result of an assertion. res is false if the assertion failed. msg is a descriptive message for
+// the failed assertion.
+type result struct {
+	res bool
+	msg string
+}
+
+// assert fails the test if assertion res failed.
+func assert(t *testing.T, res result) {
+	if !res.res {
+		t.Fatalf("expectation failed: %s", res.msg)
+	}
+}
+
+// eq asserts that the given values are equal (==).
+func eq[T comparable](expected, actual T) result {
+	return result{expected == actual, fmt.Sprintf("values not equal: expected %v but was %v", expected, actual)}
+}
+
+// nilerr asserts that the given error is nil.
+func nilerr(err error) result {
+	return result{err == nil, fmt.Sprintf("unexpected error: %v", err)}
+}
+
+// match asserts that the given slices have the same values.
+func match[S ~[]E, E comparable](expected, actual S) result {
+	return result{slices.Equal(expected, actual), fmt.Sprintf("slices not equal: expected %v but was %v", expected, actual)}
+}