Polish command help usage and commands docs

Author: robzolkos

internal/commands/commands.go

@@ -24,11 +24,11 @@ type flagInfo struct {
 	Description string `json:"description"`
 }
 
-// commandsCmd emits a flat catalog of all commands with their flags.
+// commandsCmd emits a catalog of all commands with their flags.
 var commandsCmd = &cobra.Command{
 	Use:   "commands",
 	Short: "List all available commands",
-	Long:  "Lists all available commands with their flags in JSON format.",
+	Long:  "Lists all available commands. Use --json for a structured command catalog.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		catalog := walkCommands(rootCmd, "fizzy")
 		printSuccess(catalog)

internal/commands/commands_test.go

@@ -0,0 +1,64 @@
+package commands
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/basecamp/cli/output"
+)
+
+func TestCommandsStyledOutputRendersHumanCatalog(t *testing.T) {
+	mock := NewMockClient()
+	SetTestModeWithSDK(mock)
+	SetTestFormat(output.FormatStyled)
+	defer resetTest()
+
+	if err := commandsCmd.RunE(commandsCmd, []string{}); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	raw := TestOutput()
+	if !strings.Contains(raw, "Name") {
+		t.Fatalf("expected styled catalog header, got:\n%s", raw)
+	}
+	if !strings.Contains(raw, "fizzy auth") {
+		t.Fatalf("expected styled catalog to include commands, got:\n%s", raw)
+	}
+}
+
+func TestCommandsJSONOutputReturnsStructuredCatalog(t *testing.T) {
+	mock := NewMockClient()
+	result := SetTestModeWithSDK(mock)
+	defer resetTest()
+
+	if err := commandsCmd.RunE(commandsCmd, []string{}); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if result.Response == nil || !result.Response.OK {
+		t.Fatalf("expected OK JSON response, got %#v", result.Response)
+	}
+
+	items, ok := result.Response.Data.([]any)
+	if !ok {
+		t.Fatalf("expected command catalog slice, got %#v", result.Response.Data)
+	}
+	if len(items) == 0 {
+		t.Fatal("expected command catalog entries")
+	}
+
+	found := false
+	for _, item := range items {
+		entry, ok := item.(map[string]any)
+		if !ok {
+			continue
+		}
+		if entry["name"] == "fizzy commands" {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Fatalf("expected command catalog to include fizzy commands, got %#v", items)
+	}
+}

internal/commands/help.go

@@ -133,7 +133,7 @@ func renderCommandHelp(cmd *cobra.Command, w io.Writer) {
 
 	subs := visibleSubcommands(cmd)
 	usageLine := cmd.UseLine()
-	if len(subs) > 0 {
+	if len(subs) > 0 && !cmd.Runnable() {
 		usageLine = cmd.CommandPath() + " <command> [flags]"
 	}
 
@@ -376,6 +376,7 @@ var commandExamples = map[string]string{
 	"fizzy card create":       "$ fizzy card create --board <id> --title \"Fix billing bug\"",
 	"fizzy comment list":      "$ fizzy comment list --card <number>",
 	"fizzy comment create":    "$ fizzy comment create --card <number> --body \"Looks good\"",
+	"fizzy commands":          "$ fizzy commands\n$ fizzy commands --json",
 	"fizzy search":            "$ fizzy search \"billing bug\"\n$ fizzy search \"billing bug\" --board <id>",
 	"fizzy notification":      "$ fizzy notification tray\n$ fizzy notification list",
 	"fizzy notification tray": "$ fizzy notification tray",

internal/commands/help_test.go

@@ -4,6 +4,8 @@ import (
 	"bytes"
 	"strings"
 	"testing"
+
+	"github.com/spf13/cobra"
 )
 
 func TestRenderRootHelp(t *testing.T) {
@@ -46,3 +48,44 @@ func TestRenderRootHelpOmitsCommonWorkflows(t *testing.T) {
 		t.Fatalf("expected root help to omit common workflows, got:\n%s", out)
 	}
 }
+
+func TestRenderRunnableParentCommandHelpPreservesDirectUsage(t *testing.T) {
+	configureCLIUX()
+
+	tests := []struct {
+		name string
+		cmd  *cobra.Command
+		want string
+	}{
+		{name: "signup", cmd: signupCmd, want: "  fizzy signup [flags]"},
+		{name: "setup", cmd: setupCmd, want: "  fizzy setup [flags]"},
+		{name: "skill", cmd: skillCmd, want: "  fizzy skill [flags]"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var buf bytes.Buffer
+			renderHelp(tt.cmd, &buf)
+			out := buf.String()
+
+			if !strings.Contains(out, tt.want) {
+				t.Fatalf("expected help to contain %q, got:\n%s", tt.want, out)
+			}
+		})
+	}
+}
+
+func TestRenderCommandsHelpMentionsJSONCatalog(t *testing.T) {
+	configureCLIUX()
+
+	var buf bytes.Buffer
+	renderHelp(commandsCmd, &buf)
+	out := buf.String()
+
+	if !strings.Contains(out, "Use --json for a structured command catalog.") {
+		t.Fatalf("expected commands help to mention --json catalog, got:\n%s", out)
+	}
+	if !strings.Contains(out, "EXAMPLES") || !strings.Contains(out, "$ fizzy commands --json") {
+		t.Fatalf("expected commands help examples to include --json, got:\n%s", out)
+	}
+}