fix(service): backquote metavar leak; missing-required hint names both input paths

pflag's UnquoteUsage treats a backquoted word in a flag's usage string
as the flag's metavar, so a metadata description like wiki space_id's
"可替换为`my_library`" rendered the flag as "--space-id my_library"
instead of "--space-id string". Backquotes are markdown emphasis in the
metadata prose, never meaningful in terminal help — drop them in
inlineClause so every prose surface (field description, enum option) is
covered at the one normalization point.

The pre-flight error for a missing required parameter pointed only at
`lark-cli schema <path>`, forcing a round-trip even though the recovery
is one flag away. The hint now names both input paths: the typed flag
when the binder registered one, and the --params form either way.
Whether a typed flag exists is the binder's knowledge, not cmd.Flags():
a params-only field's kebab name does resolve to a flag — the colliding
one (e.g. the output --format) — and a Lookup-based hint would steer the
reader to set the wrong flag.

Change-Id: I19c3318a3ca6159c944f993698ccaaa23af9229b

Author: liangshuo-1

cmd/service/paramflags.go

@@ -115,6 +115,22 @@ func (b *paramFlagBinder) paramsOnlyHelp() string {
 	return sb.String()
 }
 
+// hasTypedFlag reports whether the binder registered a typed flag for the
+// param named name. False for params-only fields — a flag with the same kebab
+// name may exist (that's the collision), but it is not this param's input.
+// Nil-safe for direct buildServiceRequest callers that have no binder.
+func (b *paramFlagBinder) hasTypedFlag(name string) bool {
+	if b == nil {
+		return false
+	}
+	for _, pf := range b.bound {
+		if pf.field.Name == name {
+			return true
+		}
+	}
+	return false
+}
+
 // overlay lets an explicit typed flag override the same key in --params
 // (--params is the base). Only changed flags apply, so the --params-only path is
 // unchanged. A nil binder or cmd is a no-op.

cmd/service/paramflags_test.go

@@ -4,9 +4,11 @@
 package service
 
 import (
+	"errors"
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/meta"
 	"github.com/spf13/cobra"
@@ -574,3 +576,51 @@ func TestServiceMethod_TypedFlag_HelpShowsBounds(t *testing.T) {
 		t.Errorf("flag usage should carry bounds, got %q", fl.Usage)
 	}
 }
+
+// The missing-required hint must name both recovery paths — the typed flag and
+// the --params fallback — so a reader who only knows one input style can
+// proceed without a round-trip through schema.
+func TestServiceMethod_MissingRequired_HintNamesFlagAndParams(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), imChatMembersCreate(), "create", "chat.members", nil)
+	cmd.SetArgs([]string{"--data", `{"id_list":["ou_x"]}`, "--dry-run"})
+
+	err := cmd.Execute()
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
+	}
+	for _, want := range []string{"--chat-id", `--params '{"chat_id": "<value>"}'`, "lark-cli schema im.chat.members.create"} {
+		if !strings.Contains(ve.Hint, want) {
+			t.Errorf("hint %q should contain %q", ve.Hint, want)
+		}
+	}
+}
+
+// A params-only required field (kebab name claimed by the standard --format
+// flag) has no typed flag to offer: the hint must give only the --params form,
+// never steer the reader to the colliding flag.
+func TestServiceMethod_MissingRequired_ParamsOnlyHintSkipsFlag(t *testing.T) {
+	method := meta.FromMap(map[string]interface{}{
+		"path":       "messages",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"format": map[string]interface{}{"type": "string", "location": "query", "required": true},
+		},
+	})
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), method, "list", "messages", nil)
+	cmd.SetArgs([]string{"--dry-run"})
+
+	err := cmd.Execute()
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
+	}
+	if !strings.Contains(ve.Hint, `--params '{"format": "<value>"}'`) {
+		t.Errorf("hint %q should carry the --params form", ve.Hint)
+	}
+	if strings.Contains(ve.Hint, "set --format") {
+		t.Errorf("hint %q must not steer to the colliding --format flag", ve.Hint)
+	}
+}

cmd/service/paramhelp.go

@@ -83,6 +83,11 @@ func inlineClause(s, stops string, max int) string {
 		return ""
 	}
 	s = markdownLinkRe.ReplaceAllString(s, "$1")
+	// Backquotes must go: pflag's UnquoteUsage treats a backquoted word in a
+	// flag's usage string as the flag's metavar, so a description like wiki
+	// space_id's "可替换为`my_library`" would render the flag as
+	// "--space-id my_library" instead of "--space-id string".
+	s = strings.ReplaceAll(s, "`", "")
 	if i := strings.IndexAny(s, stops); i >= 0 {
 		s = s[:i]
 	}

cmd/service/sanitize_test.go

@@ -48,3 +48,14 @@ func TestSanitizeFieldDesc_TrimsDanglingPunctuation(t *testing.T) {
 		}
 	}
 }
+
+func TestSanitizeFieldDesc_StripsBackquotes(t *testing.T) {
+	// pflag's UnquoteUsage takes a backquoted word in a flag's usage string as
+	// the flag's metavar: wiki space_id's description rendered the flag as
+	// "--space-id my_library" instead of "--space-id string".
+	in := "[知识空间id](https://x/wiki)，如果查询我的文档库可替换为`my_library`"
+	want := "知识空间id，如果查询我的文档库可替换为my_library"
+	if got := sanitizeFieldDesc(in); got != want {
+		t.Errorf("sanitizeFieldDesc(%q) = %q, want %q", in, got, want)
+	}
+}

cmd/service/service.go

@@ -472,12 +472,25 @@ func unusableParamValue(v interface{}) bool {
 	return ok && s == ""
 }
 
+// missingParamHint is the recovery hint for a missing required parameter. It
+// names both input paths — the typed flag when the binder registered one, and
+// the --params fallback — plus the schema pointer. A params-only field gets
+// only the --params form: a flag with its kebab name exists but belongs to
+// something else (e.g. the output --format), and the hint must not steer
+// there. Asking the binder, not cmd.Flags(), is what tells those apart.
+func missingParamHint(opts *ServiceMethodOptions, f meta.Field) string {
+	paramsForm := fmt.Sprintf("--params '{%q: \"<value>\"}'", f.Name)
+	if opts.binder.hasTypedFlag(f.Name) {
+		return fmt.Sprintf("set --%s <value> (or %s); see: lark-cli schema %s", f.FlagName(), paramsForm, opts.SchemaPath)
+	}
+	return fmt.Sprintf("set %s; see: lark-cli schema %s", paramsForm, opts.SchemaPath)
+}
+
 // buildServiceRequest parses flags, builds the URL with path/query params, and returns a RawApiRequest.
 // When dryRun is true and a file is provided, file reading is skipped and
 // FileUploadMeta is returned instead so the caller can render dry-run output.
 func buildServiceRequest(opts *ServiceMethodOptions) (client.RawApiRequest, *cmdutil.FileUploadMeta, error) {
 	method := opts.Method
-	schemaPath := opts.SchemaPath
 	httpMethod := method.HTTPMethod
 
 	// stdin is an io.Reader consumed at most once. Only one of --params/--data
@@ -509,7 +522,7 @@ func buildServiceRequest(opts *ServiceMethodOptions) (client.RawApiRequest, *cmd
 		if !ok || unusableParamValue(val) {
 			return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
 				"missing required path parameter: %s", s.Name).
-				WithHint("lark-cli schema %s", schemaPath).
+				WithHint("%s", missingParamHint(opts, s)).
 				WithParam(s.Name)
 		}
 		valStr := fmt.Sprintf("%v", val)
@@ -530,7 +543,7 @@ func buildServiceRequest(opts *ServiceMethodOptions) (client.RawApiRequest, *cmd
 		if s.Required && !isPaginationParam && (!exists || unusableParamValue(value)) {
 			return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
 				"missing required query parameter: %s", s.Name).
-				WithHint("lark-cli schema %s", schemaPath).
+				WithHint("%s", missingParamHint(opts, s)).
 				WithParam(s.Name)
 		}
 		if exists && !unusableParamValue(value) {