Fix help with value flags (#1006)

## Summary
- avoid routing built-in help invocations through extension probing when
known value flags are present
- initialize Cobra's default help flag before extension preflight parses
command flags
- add regression coverage for `--help` combined with `--address` and
`--namespace`

## Root Cause
Extension preflight checked raw remaining args with a string-prefix
heuristic. Values for known flags, such as `123` in `--address 123`,
looked like positional extension args, so the preflight parsed `--help`
before Cobra had registered the default help flag and surfaced `pflag:
help requested` as a real error.

Fixes #1003.

## Validation
- `go run ./cmd/temporal workflow list --address 123 --help`
- `go test ./internal/temporalcli -run 'TestHelp|TestExtension'
-count=1`
- `go test ./internal/temporalcli -count=1`

---------

Co-authored-by: alex.stanfield <13949480+chaptersix@users.noreply.github.com>

Author: kevinawoo

internal/temporalcli/commands.extension.go

@@ -31,19 +31,23 @@ func tryExecuteExtension(cctx *CommandContext, tcmd *TemporalCommand) (error, bo
 	// Find the deepest matching built-in command and remaining args.
 	foundCmd, remainingArgs, findErr := tcmd.Command.Find(cctx.Options.Args)
 
-	// Check if remaining args include positional args (not just flags).
-	// If not, a built-in command fully handles this - no extension needed.
-	hasPosArgs := slices.ContainsFunc(remainingArgs, isPosArg)
-	if findErr == nil && !hasPosArgs {
-		return nil, false
-	}
+	// Cobra normally adds --help/-h before parsing, but extension dispatch
+	// pre-parses flags before Cobra's execution path runs. We Initialize it so that
+	// help is treated as a normal CLI flag instead of surfacing as pflag.ErrHelp from flag parsing.
+	foundCmd.InitDefaultHelpFlag()
 
 	// Group args into these lists:
 	// - cliParseArgs: args to validate (subset of cliPassArgs)
 	// - cliPassArgs: known CLI args to pass to extension
 	// - extArgs: args to pass to extension and use for extension lookup
 	cliParseArgs, cliPassArgs, extArgs := groupArgs(foundCmd, remainingArgs)
 
+	// Check if remaining args include positional args (not just flags).
+	// If not, a built-in command fully handles this - no extension needed.
+	if findErr == nil && !slices.ContainsFunc(extArgs, isPosArg) {
+		return nil, false
+	}
+
 	// Search for an extension executable.
 	cmdPrefix := strings.Fields(foundCmd.CommandPath())
 	extPath, extArgs := lookupExtension(cmdPrefix, extArgs)
@@ -95,6 +99,13 @@ func groupArgs(foundCmd *cobra.Command, args []string) (cliParseArgs, cliPassArg
 
 		name, hasInline := parseFlagArg(arg)
 		if f, takesValue := lookupFlag(foundCmd, name); f != nil {
+			// Help flag after positional args should go to extArgs so it
+			// gets forwarded to extensions (e.g. "temporal foo bar --help").
+			// Before positional args it stays in cliPassArgs for Cobra to handle.
+			if f.Name == "help" && seenPos {
+				extArgs = append(extArgs, arg)
+				continue
+			}
 			// Known CLI flag: goes to cliPassArgs.
 			// Flags in cliArgsToParseForExtension also go to cliParseArgs.
 			shouldParse := cliArgsToParseForExtension[f.Name]

internal/temporalcli/commands.extension_test.go

@@ -88,6 +88,19 @@ func TestExtension_DoesNotOverrideBuiltinCommand(t *testing.T) {
 		res := h.Execute("workflow", "list", "--help")
 		assert.Contains(t, res.Stdout.String(), "List Workflow Executions")
 	})
+
+	t.Run("subcommand with value flags", func(t *testing.T) {
+		for _, args := range [][]string{
+			{"workflow", "list", "--address", "123", "--help"},
+			{"workflow", "list", "--help", "--address", "123"},
+			{"workflow", "list", "--namespace", "foo", "--help"},
+		} {
+			res := h.Execute(args...)
+			assert.Contains(t, res.Stdout.String(), "List Workflow Executions")
+			assert.NotContains(t, res.Stderr.String(), "pflag: help requested")
+			assert.NoError(t, res.Err)
+		}
+	})
 }
 
 func TestExtension_Flags(t *testing.T) {
@@ -149,6 +162,14 @@ func TestExtension_Flags(t *testing.T) {
 		{args: "workflow diagram foo --flag value", want: "temporal-workflow-diagram-foo --flag value"},     // nested commands
 		{args: "workflow diagram --output invalid", want: "temporal-workflow-diagram --output invalid"},     // invalid value passed through
 
+		// Help flags are forwarded to extensions, not handled locally.
+
+		{args: "foo --help", want: "temporal-foo --help"},
+		{args: "foo -h", want: "temporal-foo -h"},
+		{args: "foo bar --help", want: "temporal-foo-bar --help"}, // most specific extension wins
+		{args: "workflow diagram --help", want: "temporal-workflow-diagram --help"},
+		{args: "workflow diagram -h", want: "temporal-workflow-diagram -h"},
+
 		// Note: Flag aliases are already implicitly tested via other command-specific tests.
 	}
 

internal/temporalcli/commands.help_test.go

@@ -29,6 +29,21 @@ func TestHelp_Subcommand(t *testing.T) {
 	assert.NoError(t, res.Err)
 }
 
+func TestHelp_WithValueFlag(t *testing.T) {
+	h := NewCommandHarness(t)
+
+	for _, args := range [][]string{
+		{"workflow", "list", "--address", "123", "--help"},
+		{"workflow", "list", "--help", "--address", "123"},
+		{"workflow", "list", "--namespace", "foo", "--help"},
+	} {
+		res := h.Execute(args...)
+		assert.Contains(t, res.Stdout.String(), "List Workflow Executions.")
+		assert.NotContains(t, res.Stderr.String(), "pflag: help requested")
+		assert.NoError(t, res.Err)
+	}
+}
+
 func TestHelp_HelpShowsAllFlag(t *testing.T) {
 	h := NewCommandHarness(t)
 	res := h.Execute("help", "--help")