rename Runner to Commander, Describer to Descriptor, Parent to Subcommander

Author: bjaus

args.go

@@ -9,7 +9,7 @@ import (
 
 // ScanArgs inspects a command's struct tags and returns positional arg definitions.
 // This is exported so custom [HelpRenderer] implementations can inspect a command's args.
-func ScanArgs(cmd Runner) []ArgDef {
+func ScanArgs(cmd Commander) []ArgDef {
 	v := reflect.ValueOf(cmd)
 	if v.Kind() == reflect.Ptr {
 		v = v.Elem()
@@ -63,7 +63,7 @@ func scanArgsRecurse(t reflect.Type, defs *[]ArgDef) {
 
 // populateArgs sets struct fields tagged with `arg` from positional arguments,
 // environment variables, and defaults. Returns unconsumed positional arguments.
-func populateArgs(cmd Runner, args []string, envPrefix string) ([]string, error) {
+func populateArgs(cmd Commander, args []string, envPrefix string) ([]string, error) {
 	v := reflect.ValueOf(cmd)
 	if v.Kind() == reflect.Ptr {
 		v = v.Elem()

bind.go

@@ -130,7 +130,7 @@ func BindSingleton[T any](fn func() (T, error)) Option {
 
 // injectBindings populates injectable fields on all commands in the chain.
 // A field is injectable if it has no flag:, arg:, or env: tag.
-func injectBindings(chain []Runner, bindings []binding) error {
+func injectBindings(chain []Commander, bindings []binding) error {
 	if len(bindings) == 0 {
 		return nil
 	}

bind_test.go

@@ -142,8 +142,8 @@ type bindParentCmd struct {
 	DB *mockDB
 }
 
-func (c *bindParentCmd) Subcommands() []cli.Runner {
-	return []cli.Runner{&bindChildCmd{}}
+func (c *bindParentCmd) Subcommands() []cli.Commander {
+	return []cli.Commander{&bindChildCmd{}}
 }
 
 func (c *bindParentCmd) Run(ctx context.Context) error {
@@ -293,7 +293,7 @@ type singletonParentCmd struct {
 }
 
 func (c *singletonParentCmd) Run(_ context.Context) error   { return nil }
-func (c *singletonParentCmd) Subcommands() []cli.Runner     { return []cli.Runner{&singletonChildCmd{}} }
+func (c *singletonParentCmd) Subcommands() []cli.Commander     { return []cli.Commander{&singletonChildCmd{}} }
 
 type singletonChildCmd struct {
 	DB *mockDB

cli.go

@@ -9,15 +9,15 @@ import (
 	"syscall"
 )
 
-// Runner is the core interface every command must implement.
-type Runner interface {
+// Commander is the core interface every command must implement.
+type Commander interface {
 	Run(ctx context.Context) error
 }
 
-// RunFunc adapts a plain function into a [Runner].
+// RunFunc adapts a plain function into a [Commander].
 type RunFunc func(ctx context.Context) error
 
-// Run implements [Runner].
+// Run implements [Commander].
 func (f RunFunc) Run(ctx context.Context) error {
 	return f(ctx)
 }
@@ -158,7 +158,7 @@ func WithStdin(r io.Reader) Option {
 // Execute runs the command tree rooted at root with the given args and options.
 // It resolves subcommands, parses flags, runs lifecycle hooks, and executes
 // the target command.
-func Execute(ctx context.Context, root Runner, args []string, opts ...Option) error {
+func Execute(ctx context.Context, root Commander, args []string, opts ...Option) error {
 	o := defaults()
 	for _, opt := range opts {
 		opt(o)
@@ -177,7 +177,7 @@ func Execute(ctx context.Context, root Runner, args []string, opts ...Option) er
 // errors (unknown flag, missing required flag, etc.) a usage hint is appended.
 // If the error implements [ExitCoder], its exit code is used; non-nil errors
 // default to exit code 1.
-func ExecuteAndExit(ctx context.Context, root Runner, args []string, opts ...Option) {
+func ExecuteAndExit(ctx context.Context, root Commander, args []string, opts ...Option) {
 	o := defaults()
 	for _, opt := range opts {
 		opt(o)
@@ -205,7 +205,7 @@ func ExecuteAndExit(ctx context.Context, root Runner, args []string, opts ...Opt
 }
 
 // formatError writes the error message and optional usage hint to w.
-func formatError(w io.Writer, root Runner, err error) {
+func formatError(w io.Writer, root Commander, err error) {
 	fmt.Fprintf(w, "Error: %s\n", err) //nolint:errcheck
 
 	if _, isExit := err.(ExitCoder); !isExit && isFlagOrCommandError(err) {

command.go

@@ -14,17 +14,17 @@ type commandInfo struct {
 	examples        []Example
 }
 
-func resolveInfo(cmd Runner) commandInfo {
+func resolveInfo(cmd Commander) commandInfo {
 	info := commandInfo{
 		name: defaultName(cmd),
 	}
 	if n, ok := cmd.(Namer); ok {
 		info.name = n.Name()
 	}
-	if d, ok := cmd.(Describer); ok {
+	if d, ok := cmd.(Descriptor); ok {
 		info.description = d.Description()
 	}
-	if ld, ok := cmd.(LongDescriber); ok {
+	if ld, ok := cmd.(LongDescriptor); ok {
 		info.longDescription = ld.LongDescription()
 	}
 	if a, ok := cmd.(Aliaser); ok {
@@ -39,7 +39,7 @@ func resolveInfo(cmd Runner) commandInfo {
 	return info
 }
 
-func defaultName(cmd Runner) string {
+func defaultName(cmd Commander) string {
 	t := reflect.TypeOf(cmd)
 	if t.Kind() == reflect.Ptr {
 		t = t.Elem()

complete.go

@@ -31,7 +31,7 @@ const (
 // RuntimeComplete generates completion candidates for the given args and writes
 // them to w. Each candidate is one line, optionally followed by a tab and
 // description. The last line is a directive in the format ":<int>".
-func RuntimeComplete(ctx context.Context, root Runner, args []string, w io.Writer) {
+func RuntimeComplete(ctx context.Context, root Commander, args []string, w io.Writer) {
 	completions, directive := computeCompletions(ctx, root, args)
 	for _, c := range completions {
 		fmt.Fprintln(w, c) //nolint:errcheck // best-effort completion output
@@ -41,7 +41,7 @@ func RuntimeComplete(ctx context.Context, root Runner, args []string, w io.Write
 
 // computeCompletions resolves the command chain and returns completion
 // candidates with a directive.
-func computeCompletions(ctx context.Context, root Runner, args []string) ([]string, ShellCompDirective) {
+func computeCompletions(ctx context.Context, root Commander, args []string) ([]string, ShellCompDirective) {
 	// Split args: everything except last is context, last is the prefix to complete.
 	var contextArgs []string
 	var toComplete string
@@ -170,7 +170,7 @@ func computeCompletions(ctx context.Context, root Runner, args []string) ([]stri
 }
 
 // completeCommandFlags returns flag completions matching prefix.
-func completeCommandFlags(cmd Runner, prefix string) []string {
+func completeCommandFlags(cmd Commander, prefix string) []string {
 	flags := ScanFlags(cmd)
 	var candidates []string
 	for i := range flags {
@@ -222,7 +222,7 @@ func completeCommandFlags(cmd Runner, prefix string) []string {
 
 // lookupValueFlagName returns the flag name (without dashes) if arg matches
 // a non-bool, non-counter flag on cmd, or empty string if not found.
-func lookupValueFlagName(cmd Runner, arg string) string {
+func lookupValueFlagName(cmd Commander, arg string) string {
 	if !strings.HasPrefix(arg, "-") {
 		return ""
 	}
@@ -245,7 +245,7 @@ func lookupValueFlagName(cmd Runner, arg string) string {
 
 // lookupFlagEnum returns the Enum string for a flag matching the given arg
 // (e.g. "--format"), or empty if no match or no enum.
-func lookupFlagEnum(cmd Runner, arg string) string {
+func lookupFlagEnum(cmd Commander, arg string) string {
 	if !strings.HasPrefix(arg, "-") {
 		return ""
 	}

complete_test.go

@@ -17,8 +17,8 @@ type compRootCmd struct{}
 
 func (c *compRootCmd) Run(_ context.Context) error { return nil }
 func (c *compRootCmd) Name() string                { return "myapp" }
-func (c *compRootCmd) Subcommands() []cli.Runner {
-	return []cli.Runner{&compServeCmd{}, &compDeployCmd{}, &compHiddenCmd{}}
+func (c *compRootCmd) Subcommands() []cli.Commander {
+	return []cli.Commander{&compServeCmd{}, &compDeployCmd{}, &compHiddenCmd{}}
 }
 
 type compServeCmd struct {
@@ -59,17 +59,17 @@ type compNestedRoot struct{}
 
 func (c *compNestedRoot) Run(_ context.Context) error { return nil }
 func (c *compNestedRoot) Name() string                { return "myapp" }
-func (c *compNestedRoot) Subcommands() []cli.Runner {
-	return []cli.Runner{&compClusterCmd{}}
+func (c *compNestedRoot) Subcommands() []cli.Commander {
+	return []cli.Commander{&compClusterCmd{}}
 }
 
 type compClusterCmd struct{}
 
 func (c *compClusterCmd) Run(_ context.Context) error { return nil }
 func (c *compClusterCmd) Name() string                { return "cluster" }
 func (c *compClusterCmd) Description() string         { return "Manage clusters" }
-func (c *compClusterCmd) Subcommands() []cli.Runner {
-	return []cli.Runner{&compClusterListCmd{}}
+func (c *compClusterCmd) Subcommands() []cli.Commander {
+	return []cli.Commander{&compClusterListCmd{}}
 }
 
 type compClusterListCmd struct {
@@ -97,8 +97,8 @@ func (c *compCompleterNilCmd) Complete(_ context.Context, _ []string) ([]string,
 	return nil, cli.ShellCompDirectiveDefault
 }
 
-func (c *compCompleterNilCmd) Subcommands() []cli.Runner {
-	return []cli.Runner{&compServeCmd{}}
+func (c *compCompleterNilCmd) Subcommands() []cli.Commander {
+	return []cli.Commander{&compServeCmd{}}
 }
 
 // completionNames extracts flag/command names from completion candidates.

completion/command.go

@@ -8,22 +8,22 @@ import (
 	"github.com/bjaus/cli"
 )
 
-// Command returns a [cli.Runner] that prints shell completion scripts. It has
+// Command returns a [cli.Commander] that prints shell completion scripts. It has
 // bash, zsh, fish, and powershell subcommands. Output is written to w.
 // Typically added as a hidden "completion" subcommand:
 //
-//	func (a *App) Subcommands() []cli.Runner {
-//	    return []cli.Runner{
+//	func (a *App) Subcommands() []cli.Commander {
+//	    return []cli.Commander{
 //	        &serveCmd{},
 //	        completion.Command(a, "myapp", os.Stdout),
 //	    }
 //	}
-func Command(root cli.Runner, appName string, w io.Writer) cli.Runner {
+func Command(root cli.Commander, appName string, w io.Writer) cli.Commander {
 	return &completionCmd{root: root, appName: appName, out: w}
 }
 
 type completionCmd struct {
-	root    cli.Runner
+	root    cli.Commander
 	appName string
 	out     io.Writer
 }
@@ -36,8 +36,8 @@ func (c *completionCmd) Name() string        { return "completion" }
 func (c *completionCmd) Description() string { return "Generate shell completion scripts" }
 func (c *completionCmd) Hidden() bool        { return true }
 
-func (c *completionCmd) Subcommands() []cli.Runner {
-	return []cli.Runner{
+func (c *completionCmd) Subcommands() []cli.Commander {
+	return []cli.Commander{
 		&shellCmd{root: c.root, appName: c.appName, shell: "bash", out: c.out},
 		&shellCmd{root: c.root, appName: c.appName, shell: "zsh", out: c.out},
 		&shellCmd{root: c.root, appName: c.appName, shell: "fish", out: c.out},
@@ -46,7 +46,7 @@ func (c *completionCmd) Subcommands() []cli.Runner {
 }
 
 type shellCmd struct {
-	root    cli.Runner
+	root    cli.Commander
 	appName string
 	shell   string
 	out     io.Writer

completion/command_test.go

@@ -22,11 +22,11 @@ func TestCommand_Structure(t *testing.T) {
 	require.True(t, ok)
 	assert.Equal(t, "completion", n.Name())
 
-	d, ok := cmd.(cli.Describer)
+	d, ok := cmd.(cli.Descriptor)
 	require.True(t, ok)
 	assert.NotEmpty(t, d.Description())
 
-	p, ok := cmd.(cli.Parent)
+	p, ok := cmd.(cli.Subcommander)
 	require.True(t, ok)
 
 	subs := p.Subcommands()
@@ -38,7 +38,7 @@ func TestCommand_Structure(t *testing.T) {
 		require.True(t, ok)
 		assert.Equal(t, wantShells[i], n.Name())
 
-		d, ok := sub.(cli.Describer)
+		d, ok := sub.(cli.Descriptor)
 		require.True(t, ok)
 		assert.NotEmpty(t, d.Description())
 	}
@@ -74,7 +74,7 @@ func TestCommand_UsesWriter(t *testing.T) {
 	var buf bytes.Buffer
 	cmd := completion.Command(root, "myapp", &buf)
 
-	p, ok := cmd.(cli.Parent)
+	p, ok := cmd.(cli.Subcommander)
 	require.True(t, ok)
 
 	subs := p.Subcommands()
@@ -100,11 +100,11 @@ func TestCommand_ShellOutput(t *testing.T) {
 
 			var buf bytes.Buffer
 			cmd := completion.Command(root, "myapp", &buf)
-			p, ok := cmd.(cli.Parent)
+			p, ok := cmd.(cli.Subcommander)
 			require.True(t, ok)
 
 			// Find the matching shell subcommand.
-			var target cli.Runner
+			var target cli.Commander
 			for _, sub := range p.Subcommands() {
 				n, ok := sub.(cli.Namer)
 				if ok && n.Name() == shell {

completion/completion.go

@@ -1,4 +1,4 @@
-// Package completion generates shell completion scripts from a [cli.Runner]
+// Package completion generates shell completion scripts from a [cli.Commander]
 // command tree.
 //
 // Supported shells: bash, zsh, fish, and PowerShell. Each generator produces
@@ -25,7 +25,7 @@ import (
 )
 
 // Bash generates a bash completion script that calls the binary at runtime.
-func Bash(_ cli.Runner, appName string) string {
+func Bash(_ cli.Commander, appName string) string {
 	var b strings.Builder
 	safe := bashSafe(appName)
 
@@ -87,7 +87,7 @@ func Bash(_ cli.Runner, appName string) string {
 }
 
 // Zsh generates a zsh completion script that calls the binary at runtime.
-func Zsh(_ cli.Runner, appName string) string {
+func Zsh(_ cli.Commander, appName string) string {
 	var b strings.Builder
 	safe := bashSafe(appName)
 
@@ -147,7 +147,7 @@ func Zsh(_ cli.Runner, appName string) string {
 }
 
 // Fish generates a fish completion script that calls the binary at runtime.
-func Fish(_ cli.Runner, appName string) string {
+func Fish(_ cli.Commander, appName string) string {
 	var b strings.Builder
 	safe := bashSafe(appName)
 
@@ -183,7 +183,7 @@ func Fish(_ cli.Runner, appName string) string {
 }
 
 // PowerShell generates a PowerShell completion script that calls the binary at runtime.
-func PowerShell(_ cli.Runner, appName string) string {
+func PowerShell(_ cli.Commander, appName string) string {
 	var b strings.Builder
 
 	fmt.Fprintf(&b, "# PowerShell completion for %s\n\n", appName)