refactor: converge command pipelines onto a typed metadata model + catalog (#1191)

cmd/schema/schema.go

@@ -5,17 +5,17 @@ package schema
 
 import (
 	"context"
-	"fmt"
+	"errors"
 	"io"
-	"sort"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/apicatalog"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
 	"github.com/larksuite/cli/internal/schema"
-	"github.com/larksuite/cli/internal/util"
 	"github.com/spf13/cobra"
 )
 
@@ -24,336 +24,10 @@ type SchemaOptions struct {
 	Factory *cmdutil.Factory
 	Ctx     context.Context
 
-	// Positional args
-	Path      string   // first positional, when only one is given
-	ExtraArgs []string // 2nd+ positional args (space-separated form)
-
-	// Flags
-	Format string
-}
-
-func printServices(w io.Writer) {
-	services := registry.ListFromMetaProjects()
-	fmt.Fprintf(w, "%sAvailable services:%s\n\n", output.Bold, output.Reset)
-	for _, s := range services {
-		spec := registry.LoadFromMeta(s)
-		title := registry.GetStrFromMap(spec, "title")
-		if title == "" {
-			title = registry.GetStrFromMap(spec, "description")
-		}
-		fmt.Fprintf(w, "  %s%s%s  %s%s%s\n", output.Cyan, s, output.Reset, output.Dim, title, output.Reset)
-	}
-	fmt.Fprintf(w, "\n%sUsage: lark-cli schema <service>.<resource>.<method>%s\n", output.Dim, output.Reset)
-}
-
-func printResourceList(w io.Writer, spec map[string]interface{}, mode core.StrictMode) {
-	name := registry.GetStrFromMap(spec, "name")
-	version := registry.GetStrFromMap(spec, "version")
-	title := registry.GetStrFromMap(spec, "title")
-	if title == "" {
-		title = registry.GetStrFromMap(spec, "description")
-	}
-	servicePath := registry.GetStrFromMap(spec, "servicePath")
-
-	fmt.Fprintf(w, "%s%s%s (%s) — %s\n\n", output.Bold, name, output.Reset, version, title)
-	fmt.Fprintf(w, "%sBase path: %s%s\n\n", output.Dim, servicePath, output.Reset)
-
-	resources, _ := spec["resources"].(map[string]interface{})
-	for _, resName := range sortedKeys(resources) {
-		resMap, _ := resources[resName].(map[string]interface{})
-		methods, _ := resMap["methods"].(map[string]interface{})
-		methods = filterMethodsByStrictMode(methods, mode)
-		if len(methods) == 0 {
-			continue
-		}
-		fmt.Fprintf(w, "  %s%s%s\n", output.Cyan, resName, output.Reset)
-		for _, methodName := range sortedKeys(methods) {
-			m, _ := methods[methodName].(map[string]interface{})
-			httpMethod := registry.GetStrFromMap(m, "httpMethod")
-			desc := registry.GetStrFromMap(m, "description")
-			danger := ""
-			if d, _ := m["danger"].(bool); d {
-				danger = fmt.Sprintf(" %s[danger]%s", output.Red, output.Reset)
-			}
-			fmt.Fprintf(w, "    %-7s %s%s%s  %s%s%s%s\n", httpMethod, output.Bold, methodName, output.Reset, output.Dim, desc, output.Reset, danger)
-		}
-		fmt.Fprintln(w)
-	}
-	fmt.Fprintf(w, "%sUsage: lark-cli schema %s.<resource>.<method>%s\n", output.Dim, name, output.Reset)
-}
-
-// hasFileFields returns true if any requestBody field has type "file".
-func hasFileFields(method map[string]interface{}) (bool, []string) {
-	names := cmdutil.DetectFileFields(method)
-	return len(names) > 0, names
-}
-
-func printMethodDetail(w io.Writer, spec map[string]interface{}, resName, methodName string, method map[string]interface{}) {
-	servicePath := registry.GetStrFromMap(spec, "servicePath")
-	specName := registry.GetStrFromMap(spec, "name")
-	methodPath := registry.GetStrFromMap(method, "path")
-	fullPath := servicePath + "/" + methodPath
-	httpMethod := registry.GetStrFromMap(method, "httpMethod")
-	desc := registry.GetStrFromMap(method, "description")
-	isFileUpload, fileFieldNames := hasFileFields(method)
-
-	fmt.Fprintf(w, "%s%s.%s.%s%s\n\n", output.Bold, specName, resName, methodName, output.Reset)
-
-	httpColor := output.Yellow
-	if httpMethod == "GET" {
-		httpColor = output.Green
-	} else if httpMethod == "DELETE" {
-		httpColor = output.Red
-	}
-	fmt.Fprintf(w, "  %s%s%s %s\n", httpColor, httpMethod, output.Reset, fullPath)
-	if desc != "" {
-		fmt.Fprintf(w, "  %s\n", desc)
-	}
-	fmt.Fprintln(w)
-
-	// Parameters
-	params, _ := method["parameters"].(map[string]interface{})
-	if len(params) > 0 {
-		fmt.Fprintf(w, "%sParameters:%s\n\n", output.Bold, output.Reset)
-		fmt.Fprintf(w, "  %s--params%s  <json>  %soptional%s\n", output.Cyan, output.Reset, output.Dim, output.Reset)
-		for _, paramName := range sortedParamKeys(params) {
-			p, _ := params[paramName].(map[string]interface{})
-			pType := registry.GetStrFromMap(p, "type")
-			if pType == "" {
-				pType = "string"
-			}
-			location := registry.GetStrFromMap(p, "location")
-			required, _ := p["required"].(bool)
-			reqStr := fmt.Sprintf("%soptional%s", output.Dim, output.Reset)
-			if required {
-				reqStr = fmt.Sprintf("%srequired%s", output.Red, output.Reset)
-			}
-			locColor := output.Dim
-			if location == "path" {
-				locColor = output.Yellow
-			}
-			// Options (enum values)
-			optStr := formatOptions(p)
-			fmt.Fprintf(w, "      - %s%s%s (%s, %s%s%s, %s)%s\n", output.Cyan, paramName, output.Reset, pType, locColor, location, output.Reset, reqStr, optStr)
-			if pdesc := registry.GetStrFromMap(p, "description"); pdesc != "" {
-				pdesc = util.TruncateStrWithEllipsis(pdesc, 100)
-				fmt.Fprintf(w, "        %s%s%s\n", output.Dim, pdesc, output.Reset)
-			}
-			if ex := registry.GetStrFromMap(p, "example"); ex != "" {
-				fmt.Fprintf(w, "        %se.g. %s%s\n", output.Dim, ex, output.Reset)
-			}
-			if rangeStr := formatRange(p); rangeStr != "" {
-				fmt.Fprintf(w, "        %srange: %s%s\n", output.Dim, rangeStr, output.Reset)
-			}
-		}
-		fmt.Fprintln(w)
-	}
-
-	// --data for write methods
-	if httpMethod == "POST" || httpMethod == "PUT" || httpMethod == "PATCH" || httpMethod == "DELETE" {
-		if len(params) == 0 {
-			fmt.Fprintf(w, "%sParameters:%s\n\n", output.Bold, output.Reset)
-		}
-		fileUploadTag := ""
-		if isFileUpload {
-			fileUploadTag = fmt.Sprintf("  %s[file upload]%s", output.Yellow, output.Reset)
-		}
-		fmt.Fprintf(w, "  %s--data%s  <json>  %soptional%s%s\n", output.Cyan, output.Reset, output.Dim, output.Reset, fileUploadTag)
-		requestBody, _ := method["requestBody"].(map[string]interface{})
-		if len(requestBody) > 0 {
-			printNestedFields(w, requestBody, "      ", "")
-		}
-
-		if isFileUpload {
-			if len(fileFieldNames) == 1 {
-				fmt.Fprintf(w, "\n  %s--file%s  <[field=]path>  %sfile upload%s\n", output.Cyan, output.Reset, output.Dim, output.Reset)
-				fmt.Fprintf(w, "      Upload file as multipart/form-data. Default field: %q\n", fileFieldNames[0])
-			} else {
-				fmt.Fprintf(w, "\n  %s--file%s  <field=path>  %sfile upload%s\n", output.Cyan, output.Reset, output.Dim, output.Reset)
-				fmt.Fprintf(w, "      Upload file as multipart/form-data. Fields: %s\n", strings.Join(fileFieldNames, ", "))
-			}
-		}
-		fmt.Fprintln(w)
-	}
-
-	// Response
-	responseBody, _ := method["responseBody"].(map[string]interface{})
-	if len(responseBody) > 0 {
-		fmt.Fprintf(w, "%sResponse:%s\n\n", output.Bold, output.Reset)
-		printNestedFields(w, responseBody, "  ", "")
-		fmt.Fprintln(w)
-	}
-
-	// Identity
-	if tokens, ok := method["accessTokens"].([]interface{}); ok && len(tokens) > 0 {
-		var identities []string
-		for _, t := range tokens {
-			if s, ok := t.(string); ok {
-				switch s {
-				case "user":
-					identities = append(identities, "user")
-				case "tenant":
-					identities = append(identities, "bot")
-				}
-			}
-		}
-		if len(identities) > 0 {
-			fmt.Fprintf(w, "%sIdentity:%s %s\n", output.Bold, output.Reset, strings.Join(identities, ", "))
-		}
-	}
-
-	// Scopes (all)
-	if scopes, ok := method["scopes"].([]interface{}); ok && len(scopes) > 0 {
-		var scopeStrs []string
-		for _, s := range scopes {
-			if str, ok := s.(string); ok {
-				scopeStrs = append(scopeStrs, str)
-			}
-		}
-		fmt.Fprintf(w, "%sScopes:%s   %s\n", output.Bold, output.Reset, strings.Join(scopeStrs, ", "))
-	}
-
-	// CLI example
-	if isFileUpload && len(fileFieldNames) == 1 {
-		fmt.Fprintf(w, "%sCLI:%s      lark-cli %s %s %s --file <path>\n", output.Bold, output.Reset, specName, resName, methodName)
-	} else if isFileUpload {
-		fmt.Fprintf(w, "%sCLI:%s      lark-cli %s %s %s --file <field=path>\n", output.Bold, output.Reset, specName, resName, methodName)
-	} else {
-		fmt.Fprintf(w, "%sCLI:%s      lark-cli %s %s %s\n", output.Bold, output.Reset, specName, resName, methodName)
-	}
-
-	// Docs
-	if docUrl := registry.GetStrFromMap(method, "docUrl"); docUrl != "" {
-		fmt.Fprintf(w, "%sDocs:%s     %s\n", output.Bold, output.Reset, docUrl)
-	}
-}
-
-func printNestedFields(w io.Writer, fields map[string]interface{}, indent, prefix string) {
-	for _, fieldName := range sortedFieldKeys(fields) {
-		f, _ := fields[fieldName].(map[string]interface{})
-		fullName := fieldName
-		if prefix != "" {
-			fullName = prefix + "." + fieldName
-		}
-		fType := registry.GetStrFromMap(f, "type")
-		required, _ := f["required"].(bool)
-		reqStr := fmt.Sprintf("%soptional%s", output.Dim, output.Reset)
-		if required {
-			reqStr = fmt.Sprintf("%srequired%s", output.Red, output.Reset)
-		}
-		optStr := formatOptions(f)
-		fmt.Fprintf(w, "%s- %s%s%s (%s, %s)%s\n", indent, output.Cyan, fullName, output.Reset, fType, reqStr, optStr)
-		desc := registry.GetStrFromMap(f, "description")
-		if desc != "" {
-			desc = util.TruncateStrWithEllipsis(desc, 100)
-			fmt.Fprintf(w, "%s  %s%s%s\n", indent, output.Dim, desc, output.Reset)
-		}
-		if ex := registry.GetStrFromMap(f, "example"); ex != "" {
-			fmt.Fprintf(w, "%s  %se.g. %s%s\n", indent, output.Dim, ex, output.Reset)
-		}
-		if rangeStr := formatRange(f); rangeStr != "" {
-			fmt.Fprintf(w, "%s  %srange: %s%s\n", indent, output.Dim, rangeStr, output.Reset)
-		}
-		if props, ok := f["properties"].(map[string]interface{}); ok && len(props) > 0 {
-			printNestedFields(w, props, indent+"  ", fullName)
-		}
-	}
-}
-
-// formatOptions returns " — val1 | val2 | ..." if field has options, else "".
-func formatOptions(f map[string]interface{}) string {
-	opts, ok := f["options"].([]interface{})
-	if !ok || len(opts) == 0 {
-		return ""
-	}
-	var vals []string
-	for _, o := range opts {
-		if om, ok := o.(map[string]interface{}); ok {
-			if v := registry.GetStrFromMap(om, "value"); v != "" {
-				vals = append(vals, v)
-			}
-		}
-	}
-	if len(vals) == 0 {
-		return ""
-	}
-	return fmt.Sprintf(" %s— %s%s", output.Dim, strings.Join(vals, " | "), output.Reset)
-}
-
-// formatRange returns "min..max" if field has min/max, else "".
-func formatRange(f map[string]interface{}) string {
-	minVal := registry.GetStrFromMap(f, "min")
-	maxVal := registry.GetStrFromMap(f, "max")
-	if minVal == "" && maxVal == "" {
-		return ""
-	}
-	if minVal != "" && maxVal != "" {
-		return minVal + ".." + maxVal
-	}
-	if minVal != "" {
-		return ">=" + minVal
-	}
-	return "<=" + maxVal
-}
-
-// sortedKeys returns map keys in alphabetical order.
-func sortedKeys(m map[string]interface{}) []string {
-	keys := make([]string, 0, len(m))
-	for k := range m {
-		keys = append(keys, k)
-	}
-	sort.Strings(keys)
-	return keys
-}
-
-// sortedParamKeys returns parameter keys sorted: required first, then alphabetical.
-func sortedParamKeys(params map[string]interface{}) []string {
-	keys := make([]string, 0, len(params))
-	for k := range params {
-		keys = append(keys, k)
-	}
-	sort.Slice(keys, func(i, j int) bool {
-		pi, _ := params[keys[i]].(map[string]interface{})
-		pj, _ := params[keys[j]].(map[string]interface{})
-		ri, _ := pi["required"].(bool)
-		rj, _ := pj["required"].(bool)
-		if ri != rj {
-			return ri
-		}
-		return keys[i] < keys[j]
-	})
-	return keys
-}
-
-// sortedFieldKeys returns field keys sorted: required first, then alphabetical.
-func sortedFieldKeys(fields map[string]interface{}) []string {
-	keys := make([]string, 0, len(fields))
-	for k := range fields {
-		keys = append(keys, k)
-	}
-	sort.Slice(keys, func(i, j int) bool {
-		fi, _ := fields[keys[i]].(map[string]interface{})
-		fj, _ := fields[keys[j]].(map[string]interface{})
-		ri, _ := fi["required"].(bool)
-		rj, _ := fj["required"].(bool)
-		if ri != rj {
-			return ri
-		}
-		return keys[i] < keys[j]
-	})
-	return keys
-}
-
-func findResourceByPath(resources map[string]interface{}, parts []string) (map[string]interface{}, string, []string) {
-	for i := len(parts); i >= 1; i-- {
-		candidateName := strings.Join(parts[:i], ".")
-		if res, ok := resources[candidateName]; ok {
-			if resMap, ok := res.(map[string]interface{}); ok {
-				return resMap, candidateName, parts[i:]
-			}
-		}
-	}
-	return nil, "", nil
+	// Args are the positional path segments, in either the dotted single-arg
+	// form ("im.messages.reply") or the space-separated form ("im messages
+	// reply"); apicatalog.ParsePath normalizes both.
+	Args []string
 }
 
 // NewCmdSchema creates the schema command. If runF is non-nil it is called instead of schemaRun (test hook).
@@ -365,12 +39,7 @@ func NewCmdSchema(f *cmdutil.Factory, runF func(*SchemaOptions) error) *cobra.Co
 		Short: "View API method parameters, types, and scopes",
 		Args:  cobra.MaximumNArgs(8),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			if len(args) > 0 {
-				opts.Path = args[0]
-			}
-			if len(args) > 1 {
-				opts.ExtraArgs = args[1:]
-			}
+			opts.Args = append([]string(nil), args...)
 			opts.Ctx = cmd.Context()
 			if runF != nil {
 				return runF(opts)
@@ -380,433 +49,89 @@ func NewCmdSchema(f *cmdutil.Factory, runF func(*SchemaOptions) error) *cobra.Co
 	}
 	cmdutil.DisableAuthCheck(cmd)
 
+	// Tolerated for agent compatibility; ignored — schema only emits the JSON
+	// envelope, and its output is identity-independent (strict-mode filtering
+	// comes from ResolveStrictMode, never from --as).
+	cmd.Flags().String("format", "json", "")
+	cmd.Flags().Bool("json", true, "")
+	cmd.Flags().String("as", "", "")
+	_ = cmd.Flags().MarkHidden("format")
+	_ = cmd.Flags().MarkHidden("json")
+	_ = cmd.Flags().MarkHidden("as")
+
 	cmd.ValidArgsFunction = completeSchemaPath(f)
-	cmd.Flags().StringVar(&opts.Format, "format", "json", "output format: json (default) | pretty")
-	cmdutil.RegisterFlagCompletion(cmd, "format", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
-		return []string{"json", "pretty"}, cobra.ShellCompDirectiveNoFileComp
-	})
 	cmdutil.SetRisk(cmd, cmdutil.RiskRead)
 
 	return cmd
 }
 
-// completeSchemaPath provides tab-completion for the schema path argument.
-// It handles both legacy dotted resource names (e.g. app.table.fields) and the
-// newer space-separated form (e.g. `schema im messages reply`).
+// completeSchemaPath is a thin adapter over the embedded catalog's Complete.
+// It uses the embedded source so completion candidates match what `schema`
+// execution can resolve (both overlay-free).
 func completeSchemaPath(f *cmdutil.Factory) func(*cobra.Command, []string, string) ([]string, cobra.ShellCompDirective) {
 	return func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 		mode := f.ResolveStrictMode(cmd.Context())
-
-		// Case 1: legacy "single dotted arg" path — no previous args yet
-		if len(args) == 0 {
-			parts := strings.Split(toComplete, ".")
-			if len(parts) <= 1 {
-				var completions []string
-				for _, s := range registry.ListFromMetaProjects() {
-					if strings.HasPrefix(s, toComplete) {
-						completions = append(completions, s+".")
-					}
-				}
-				return completions, cobra.ShellCompDirectiveNoFileComp | cobra.ShellCompDirectiveNoSpace
-			}
-			serviceName := parts[0]
-			spec := registry.LoadFromMeta(serviceName)
-			if spec == nil {
-				return nil, cobra.ShellCompDirectiveNoFileComp
-			}
-			spec = filterSpecByStrictMode(spec, mode)
-			resources, _ := spec["resources"].(map[string]interface{})
-			if resources == nil {
-				return nil, cobra.ShellCompDirectiveNoFileComp
-			}
-			afterService := strings.Join(parts[1:], ".")
-			completions := completeSchemaPathForSpec(serviceName, resources, afterService)
-			allTrailingDot := len(completions) > 0
-			for _, c := range completions {
-				if !strings.HasSuffix(c, ".") {
-					allTrailingDot = false
-					break
-				}
-			}
-			directive := cobra.ShellCompDirectiveNoFileComp
-			if allTrailingDot {
-				directive |= cobra.ShellCompDirectiveNoSpace
-			}
-			return completions, directive
+		completions, noSpace := registry.EmbeddedCatalog().Complete(args, toComplete, registry.FilterForStrictMode(mode))
+		directive := cobra.ShellCompDirectiveNoFileComp
+		if noSpace {
+			directive |= cobra.ShellCompDirectiveNoSpace
 		}
-
-		// Case 2: space-form, args already has segments
-		// Walk down service -> resource(s) -> method based on existing args
-		serviceName := args[0]
-		spec := registry.LoadFromMeta(serviceName)
-		if spec == nil {
-			return nil, cobra.ShellCompDirectiveNoFileComp
-		}
-		spec = filterSpecByStrictMode(spec, mode)
-		resources, _ := spec["resources"].(map[string]interface{})
-		if resources == nil {
-			return nil, cobra.ShellCompDirectiveNoFileComp
-		}
-
-		// args[1:] are resource path segments (possibly partial); current
-		// toComplete is the next segment under cursor.
-		consumed := args[1:]
-		resource, _, remaining := findResourceByPath(resources, consumed)
-		if resource == nil {
-			// Suggest top-level resource names that match toComplete
-			var completions []string
-			for resName := range resources {
-				if strings.HasPrefix(resName, toComplete) {
-					completions = append(completions, resName)
-				}
-			}
-			sort.Strings(completions)
-			return completions, cobra.ShellCompDirectiveNoFileComp
-		}
-		if len(remaining) > 0 {
-			// Already typed past the resource — suggest methods
-			methods, _ := resource["methods"].(map[string]interface{})
-			methods = filterMethodsByStrictMode(methods, mode)
-			var completions []string
-			for mName := range methods {
-				if strings.HasPrefix(mName, toComplete) {
-					completions = append(completions, mName)
-				}
-			}
-			sort.Strings(completions)
-			return completions, cobra.ShellCompDirectiveNoFileComp
-		}
-		// Resource matched exactly, suggest methods
-		methods, _ := resource["methods"].(map[string]interface{})
-		methods = filterMethodsByStrictMode(methods, mode)
-		var completions []string
-		for mName := range methods {
-			if strings.HasPrefix(mName, toComplete) {
-				completions = append(completions, mName)
-			}
-		}
-		sort.Strings(completions)
-		return completions, cobra.ShellCompDirectiveNoFileComp
+		return completions, directive
 	}
 }
 
-func completeSchemaPathForSpec(serviceName string, resources map[string]interface{}, afterService string) []string {
-	var completions []string
-
-	for resName, resVal := range resources {
-		if strings.HasPrefix(resName, afterService) {
-			completions = append(completions, serviceName+"."+resName+".")
-			continue
-		}
-		if !strings.HasPrefix(afterService, resName+".") {
-			continue
-		}
-		methodPrefix := afterService[len(resName)+1:]
-		resMap, _ := resVal.(map[string]interface{})
-		if resMap == nil {
-			continue
-		}
-		methods, _ := resMap["methods"].(map[string]interface{})
-		for methodName := range methods {
-			if strings.HasPrefix(methodName, methodPrefix) {
-				completions = append(completions, serviceName+"."+resName+"."+methodName)
-			}
-		}
-	}
-
-	sort.Strings(completions)
-	return completions
-}
-
 func schemaRun(opts *SchemaOptions) error {
 	out := opts.Factory.IOStreams.Out
 	mode := opts.Factory.ResolveStrictMode(opts.Ctx)
-
-	// args may have arrived as a single string (legacy single-arg path) or
-	// split into multiple — normalize to a single args slice.
-	var rawArgs []string
-	if opts.Path != "" {
-		rawArgs = []string{opts.Path}
-	}
-	if len(opts.ExtraArgs) > 0 {
-		if opts.Path != "" {
-			rawArgs = append([]string{opts.Path}, opts.ExtraArgs...)
-		} else {
-			rawArgs = append([]string(nil), opts.ExtraArgs...)
-		}
-	}
-	parts := schema.ParsePath(rawArgs)
-
-	if opts.Format == "pretty" {
-		return runPrettyMode(out, parts, mode)
-	}
-	return runJSONMode(out, parts, mode)
+	return runSchema(out, apicatalog.ParsePath(opts.Args), mode)
 }
 
-// runJSONMode dispatches list/single envelope output based on parts.
-// JSON mode uses embedded data only (bypasses remote overlay) so envelope
-// output is deterministic across machines.
-func runJSONMode(out io.Writer, parts []string, mode core.StrictMode) error {
-	filter := strictModeFilter(mode)
-
-	switch len(parts) {
-	case 0:
-		envs := schema.AssembleAll(filter)
-		output.PrintJson(out, envs)
-		return nil
-	case 1:
-		spec := registry.EmbeddedSpec(parts[0])
-		if spec == nil {
-			return errUnknownEmbeddedService(parts[0])
+// runSchema resolves the path through the embedded catalog and renders the
+// matching envelope(s). The catalog owns navigation (Resolve + MethodRefs) and
+// schema owns rendering (Envelope/Envelopes); this adapter only chooses the
+// output shape — a single resolved method renders as one envelope object,
+// anything broader as an array — and maps resolve failures to hints.
+func runSchema(out io.Writer, parts []string, mode core.StrictMode) error {
+	catalog := registry.EmbeddedCatalog()
+	target, err := catalog.Resolve(parts)
+	if err != nil {
+		return resolveError(err)
+	}
+	refs := catalog.MethodRefs(target, registry.FilterForStrictMode(mode))
+	if target.Kind == apicatalog.TargetMethod {
+		if len(refs) == 0 {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument,
+				"Method %s not available in current identity mode", target.Method.SchemaPath()).
+				WithHint("strict mode hides methods the active account identity cannot call; it is shown for an identity (user or bot) that has the required access token")
 		}
-		envs := schema.AssembleService(parts[0], spec, filter)
-		output.PrintJson(out, envs)
-		return nil
-	default:
-		return runJSONForPath(out, parts, filter)
-	}
-}
-
-// runJSONForPath handles len(parts) >= 2: try resource match first, fallback
-// to single-method match. Uses embedded data only.
-func runJSONForPath(out io.Writer, parts []string, filter schema.MethodFilter) error {
-	serviceName := parts[0]
-	spec := registry.EmbeddedSpec(serviceName)
-	if spec == nil {
-		return errUnknownEmbeddedService(serviceName)
-	}
-	resources, _ := spec["resources"].(map[string]interface{})
-	resource, resName, remaining := findResourceByPath(resources, parts[1:])
-	if resource == nil {
-		var names []string
-		for k := range resources {
-			names = append(names, k)
-		}
-		sort.Strings(names)
-		return output.ErrWithHint(output.ExitValidation, "validation",
-			fmt.Sprintf("Unknown resource: %s.%s", serviceName, strings.Join(parts[1:], ".")),
-			fmt.Sprintf("Available: %s", strings.Join(names, ", ")))
-	}
-	if len(remaining) == 0 {
-		// Resource-scoped envelope array
-		envs := assembleResource(serviceName, resName, resource, filter)
-		output.PrintJson(out, envs)
+		output.PrintJson(out, schema.EnvelopeOf(refs[0]))
 		return nil
 	}
-	methodName := remaining[0]
-	methods, _ := resource["methods"].(map[string]interface{})
-	method, ok := methods[methodName].(map[string]interface{})
-	if !ok {
-		var names []string
-		for k := range methods {
-			names = append(names, k)
-		}
-		sort.Strings(names)
-		return output.ErrWithHint(output.ExitValidation, "validation",
-			fmt.Sprintf("Unknown method: %s.%s.%s", serviceName, resName, methodName),
-			fmt.Sprintf("Available: %s", strings.Join(names, ", ")))
-	}
-	if len(remaining) > 1 {
-		// Method exists but caller appended extra segments — reject so they
-		// don't silently get this method's schema when they typo'd the path.
-		return output.ErrWithHint(output.ExitValidation, "validation",
-			fmt.Sprintf("Unknown path: %s.%s.%s",
-				serviceName, resName, strings.Join(remaining, ".")),
-			fmt.Sprintf("Method %q exists but the trailing segments %q do not resolve",
-				methodName, strings.Join(remaining[1:], ".")))
-	}
-	if filter != nil && !filter(method) {
-		// Method exists in spec but filtered out by strict mode
-		return output.ErrWithHint(output.ExitValidation, "validation",
-			fmt.Sprintf("Method %s.%s.%s not available in current identity mode", serviceName, resName, methodName),
-			"Use --as user / --as bot to switch")
-	}
-	env := schema.AssembleEnvelope(serviceName, []string{resName}, methodName, method)
-	output.PrintJson(out, env)
+	output.PrintJson(out, schema.Envelopes(refs))
 	return nil
 }
 
-func assembleResource(serviceName, resName string, resource map[string]interface{}, filter schema.MethodFilter) []schema.Envelope {
-	methods, _ := resource["methods"].(map[string]interface{})
-	resourcePath := []string{resName}
-	var envs []schema.Envelope
-	for methodName, raw := range methods {
-		method, ok := raw.(map[string]interface{})
-		if !ok {
-			continue
-		}
-		if filter != nil && !filter(method) {
-			continue
-		}
-		envs = append(envs, schema.AssembleEnvelope(serviceName, resourcePath, methodName, method))
+// resolveError maps a catalog *ResolveError to a typed *errs.ValidationError
+// (CategoryValidation drives the exit code; Hint promotes to the envelope),
+// preserving the historical message + hint text.
+func resolveError(err error) error {
+	var re *apicatalog.ResolveError
+	if !errors.As(err, &re) {
+		return err
 	}
-	sort.Slice(envs, func(i, j int) bool { return envs[i].Name < envs[j].Name })
-	return envs
-}
-
-// runPrettyMode preserves the existing legacy pretty rendering verbatim.
-// All printServices/printResourceList/printMethodDetail calls stay unchanged.
-func runPrettyMode(out io.Writer, parts []string, mode core.StrictMode) error {
-	if len(parts) == 0 {
-		printServices(out)
-		return nil
-	}
-	serviceName := parts[0]
-	spec := registry.LoadFromMeta(serviceName)
-	if spec == nil {
-		return errUnknownService(serviceName)
-	}
-	if len(parts) == 1 {
-		printResourceList(out, spec, mode)
-		return nil
-	}
-	resources, _ := spec["resources"].(map[string]interface{})
-	resource, resName, remaining := findResourceByPath(resources, parts[1:])
-	if resource == nil {
-		var names []string
-		for k := range resources {
-			names = append(names, k)
-		}
-		sort.Strings(names)
-		return output.ErrWithHint(output.ExitValidation, "validation",
-			fmt.Sprintf("Unknown resource: %s.%s", serviceName, strings.Join(parts[1:], ".")),
-			fmt.Sprintf("Available: %s", strings.Join(names, ", ")))
-	}
-	if len(remaining) == 0 {
-		fmt.Fprintf(out, "%s%s.%s%s\n\n", output.Bold, serviceName, resName, output.Reset)
-		methods, _ := resource["methods"].(map[string]interface{})
-		methods = filterMethodsByStrictMode(methods, mode)
-		for _, mName := range sortedKeys(methods) {
-			m, _ := methods[mName].(map[string]interface{})
-			httpMethod := registry.GetStrFromMap(m, "httpMethod")
-			desc := registry.GetStrFromMap(m, "description")
-			fmt.Fprintf(out, "  %-7s %s%s%s  %s%s%s\n", httpMethod, output.Bold, mName, output.Reset, output.Dim, desc, output.Reset)
-		}
-		fmt.Fprintf(out, "\n%sUsage: lark-cli schema %s.%s.<method>%s\n", output.Dim, serviceName, resName, output.Reset)
-		return nil
-	}
-	methodName := remaining[0]
-	methods, _ := resource["methods"].(map[string]interface{})
-	methods = filterMethodsByStrictMode(methods, mode)
-	method, ok := methods[methodName].(map[string]interface{})
-	if !ok {
-		var names []string
-		for k := range methods {
-			names = append(names, k)
-		}
-		sort.Strings(names)
-		return output.ErrWithHint(output.ExitValidation, "validation",
-			fmt.Sprintf("Unknown method: %s.%s.%s", serviceName, resName, methodName),
-			fmt.Sprintf("Available: %s", strings.Join(names, ", ")))
-	}
-	if len(remaining) > 1 {
-		return output.ErrWithHint(output.ExitValidation, "validation",
-			fmt.Sprintf("Unknown path: %s.%s.%s",
-				serviceName, resName, strings.Join(remaining, ".")),
-			fmt.Sprintf("Method %q exists but the trailing segments %q do not resolve",
-				methodName, strings.Join(remaining[1:], ".")))
-	}
-	printMethodDetail(out, spec, resName, methodName, method)
-	return nil
-}
-
-// strictModeFilter adapts core.StrictMode into a schema.MethodFilter, or returns
-// nil if strict mode is not active.
-func strictModeFilter(mode core.StrictMode) schema.MethodFilter {
-	if !mode.IsActive() {
-		return nil
-	}
-	token := registry.IdentityToAccessToken(string(mode.ForcedIdentity()))
-	return func(method map[string]interface{}) bool {
-		tokens, _ := method["accessTokens"].([]interface{})
-		if tokens == nil {
-			return true // permissive when meta_data lacks accessTokens
-		}
-		for _, t := range tokens {
-			if s, _ := t.(string); s == token {
-				return true
-			}
-		}
-		return false
-	}
-}
-
-func errUnknownService(name string) error {
-	return output.ErrWithHint(output.ExitValidation, "validation",
-		fmt.Sprintf("Unknown service: %s", name),
-		fmt.Sprintf("Available: %s", strings.Join(registry.ListFromMetaProjects(), ", ")))
-}
-
-// errUnknownEmbeddedService is the JSON-mode variant: it lists only embedded
-// services (no overlay) because JSON mode itself bypasses overlay; suggesting
-// overlay-only services would mislead callers when those services subsequently
-// fail to resolve in envelope output.
-func errUnknownEmbeddedService(name string) error {
-	return output.ErrWithHint(output.ExitValidation, "validation",
-		fmt.Sprintf("Unknown service: %s", name),
-		fmt.Sprintf("Available: %s", strings.Join(registry.EmbeddedServiceNames(), ", ")))
-}
-
-// filterSpecByStrictMode returns a shallow copy of spec with each resource's methods
-// filtered by strict mode. Returns the original spec when strict mode is off.
-func filterSpecByStrictMode(spec map[string]interface{}, mode core.StrictMode) map[string]interface{} {
-	if !mode.IsActive() {
-		return spec
-	}
-	result := make(map[string]interface{}, len(spec))
-	for k, v := range spec {
-		result[k] = v
-	}
-	resources, _ := spec["resources"].(map[string]interface{})
-	if resources == nil {
-		return result
-	}
-	filteredRes := make(map[string]interface{}, len(resources))
-	for resName, resVal := range resources {
-		resMap, ok := resVal.(map[string]interface{})
-		if !ok {
-			continue
-		}
-		methods, _ := resMap["methods"].(map[string]interface{})
-		filtered := filterMethodsByStrictMode(methods, mode)
-		if len(filtered) == 0 {
-			continue
-		}
-		resCopy := make(map[string]interface{}, len(resMap))
-		for k, v := range resMap {
-			resCopy[k] = v
-		}
-		resCopy["methods"] = filtered
-		filteredRes[resName] = resCopy
-	}
-	result["resources"] = filteredRes
-	return result
-}
-
-// filterMethodsByStrictMode removes methods incompatible with the active strict mode.
-// Returns the original map unmodified when strict mode is off.
-func filterMethodsByStrictMode(methods map[string]interface{}, mode core.StrictMode) map[string]interface{} {
-	if !mode.IsActive() || methods == nil {
-		return methods
-	}
-	token := registry.IdentityToAccessToken(string(mode.ForcedIdentity()))
-	filtered := make(map[string]interface{}, len(methods))
-	for name, val := range methods {
-		m, ok := val.(map[string]interface{})
-		if !ok {
-			continue
-		}
-		tokens, _ := m["accessTokens"].([]interface{})
-		if tokens == nil {
-			filtered[name] = val
-			continue
-		}
-		for _, t := range tokens {
-			if ts, ok := t.(string); ok && ts == token {
-				filtered[name] = val
-				break
-			}
-		}
-	}
-	return filtered
+	switch re.Kind {
+	case apicatalog.ErrService:
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "Unknown service: %s", re.Subject).
+			WithHint("Available: %s", strings.Join(re.Candidates, ", "))
+	case apicatalog.ErrResource:
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "Unknown resource: %s", re.Subject).
+			WithHint("Available: %s", strings.Join(re.Candidates, ", "))
+	case apicatalog.ErrMethod:
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "Unknown method: %s", re.Subject).
+			WithHint("Available: %s", strings.Join(re.Candidates, ", "))
+	case apicatalog.ErrPath:
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "Unknown path: %s", re.Subject).
+			WithHint("Method %q exists but the trailing segments %q do not resolve", re.Method, re.Trailing)
+	}
+	return err
 }

cmd/schema/schema_test.go

@@ -4,7 +4,6 @@
 package schema
 
 import (
-	"bytes"
 	"encoding/json"
 	"strings"
 	"testing"
@@ -21,29 +20,46 @@ func TestSchemaCmd_FlagParsing(t *testing.T) {
 		gotOpts = opts
 		return nil
 	})
-	cmd.SetArgs([]string{"calendar.events.list", "--format", "pretty"})
+	cmd.SetArgs([]string{"calendar.events.list"})
 	err := cmd.Execute()
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	if gotOpts.Path != "calendar.events.list" {
-		t.Errorf("expected path calendar.events.list, got %s", gotOpts.Path)
-	}
-	if gotOpts.Format != "pretty" {
-		t.Errorf("expected Format=pretty, got %s", gotOpts.Format)
+	if len(gotOpts.Args) != 1 || gotOpts.Args[0] != "calendar.events.list" {
+		t.Errorf("expected args [calendar.events.list], got %v", gotOpts.Args)
 	}
 }
 
-func TestSchemaCmd_NoArgs_Pretty(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
-
-	cmd := NewCmdSchema(f, nil)
-	cmd.SetArgs([]string{"--format", "pretty"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
+func TestSchemaCmd_OutputFlagsAcceptedForCompat(t *testing.T) {
+	// Agents are habituated to --format/--json/--as from api/service commands.
+	// schema must accept them without erroring and always emit the JSON envelope —
+	// its output is structured JSON and identity-independent, so the values have
+	// no effect.
+	argSets := [][]string{
+		{"--format", "json"},
+		{"--format", "pretty"},
+		{"--format", "table"}, // no table rendering for a nested schema -> JSON
+		{"--format", "csv"},
+		{"--json"},
+		{"--json", "--format", "ndjson"},
+		{"--as", "user"},
+		{"--as", "bot"},
+		{"--as", "user", "--json"},
 	}
-	if !strings.Contains(stdout.String(), "Available services") {
-		t.Error("expected service list in pretty mode")
+	for _, extra := range argSets {
+		f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+		cmd := NewCmdSchema(f, nil)
+		cmd.SetArgs(append([]string{"im.images.create"}, extra...))
+		if err := cmd.Execute(); err != nil {
+			t.Fatalf("args %v should be accepted, got error: %v", extra, err)
+		}
+		var env map[string]interface{}
+		if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+			t.Fatalf("args %v: output is not a JSON envelope: %v\n%s", extra, err, stdout.String())
+		}
+		if env["name"] != "im images create" {
+			t.Errorf("args %v: expected the im images create envelope, got name=%v", extra, env["name"])
+		}
 	}
 }
 
@@ -51,7 +67,7 @@ func TestSchemaCmd_NoArgs_JSON_IsArray(t *testing.T) {
 	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
 
 	cmd := NewCmdSchema(f, nil)
-	cmd.SetArgs([]string{}) // default --format json
+	cmd.SetArgs([]string{})
 	if err := cmd.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -76,7 +92,7 @@ func TestSchemaCmd_JSONIsEnvelope(t *testing.T) {
 	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
 
 	cmd := NewCmdSchema(f, nil)
-	cmd.SetArgs([]string{"im.images.create", "--format", "json"})
+	cmd.SetArgs([]string{"im.images.create"})
 	if err := cmd.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -179,23 +195,6 @@ func TestSchemaCmd_NoYesForReadRisk(t *testing.T) {
 	}
 }
 
-func TestSchemaCmd_PrettyUnchanged_KeyTextPresent(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
-
-	cmd := NewCmdSchema(f, nil)
-	cmd.SetArgs([]string{"im.images.create", "--format", "pretty"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	out := stdout.String()
-	// Existing pretty rendering surfaces these markers — they must still appear
-	for _, want := range []string{"Parameters:", "Response:", "Identity:", "Scopes:", "CLI:"} {
-		if !strings.Contains(out, want) {
-			t.Errorf("pretty output missing marker %q", want)
-		}
-	}
-}
-
 func TestSchemaCmd_UnknownService(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
@@ -212,168 +211,6 @@ func TestSchemaCmd_UnknownService(t *testing.T) {
 	}
 }
 
-func TestPrintMethodDetail_FileUpload(t *testing.T) {
-	spec := map[string]interface{}{
-		"name":        "im",
-		"servicePath": "/open-apis/im/v1",
-	}
-	method := map[string]interface{}{
-		"path":        "images",
-		"httpMethod":  "POST",
-		"description": "Upload an image",
-		"requestBody": map[string]interface{}{
-			"image_type": map[string]interface{}{
-				"type":     "string",
-				"required": true,
-			},
-			"image": map[string]interface{}{
-				"type":     "file",
-				"required": true,
-			},
-		},
-		"accessTokens": []interface{}{"user", "tenant"},
-	}
-
-	var buf bytes.Buffer
-	printMethodDetail(&buf, spec, "images", "create", method)
-	out := buf.String()
-
-	if !strings.Contains(out, "file upload") {
-		t.Errorf("expected 'file upload' marker in output, got:\n%s", out)
-	}
-	if !strings.Contains(out, "--file") {
-		t.Errorf("expected '--file' in output, got:\n%s", out)
-	}
-	if !strings.Contains(out, `"image"`) {
-		t.Errorf("expected default field name 'image' in output, got:\n%s", out)
-	}
-	if !strings.Contains(out, "--file <path>") {
-		t.Errorf("expected CLI example with --file <path>, got:\n%s", out)
-	}
-}
-
-func TestPrintMethodDetail_NoFileUpload(t *testing.T) {
-	spec := map[string]interface{}{
-		"name":        "calendar",
-		"servicePath": "/open-apis/calendar/v4",
-	}
-	method := map[string]interface{}{
-		"path":        "events",
-		"httpMethod":  "POST",
-		"description": "Create an event",
-		"requestBody": map[string]interface{}{
-			"summary": map[string]interface{}{
-				"type":     "string",
-				"required": true,
-			},
-		},
-	}
-
-	var buf bytes.Buffer
-	printMethodDetail(&buf, spec, "events", "create", method)
-	out := buf.String()
-
-	if strings.Contains(out, "file upload") {
-		t.Errorf("did not expect 'file upload' marker for non-file method, got:\n%s", out)
-	}
-	if strings.Contains(out, "--file") {
-		t.Errorf("did not expect '--file' for non-file method, got:\n%s", out)
-	}
-}
-
-func TestHasFileFields(t *testing.T) {
-	tests := []struct {
-		name       string
-		method     map[string]interface{}
-		wantBool   bool
-		wantFields []string
-	}{
-		{
-			name: "has file field",
-			method: map[string]interface{}{
-				"requestBody": map[string]interface{}{
-					"image": map[string]interface{}{"type": "file"},
-					"name":  map[string]interface{}{"type": "string"},
-				},
-			},
-			wantBool:   true,
-			wantFields: []string{"image"},
-		},
-		{
-			name: "no file field",
-			method: map[string]interface{}{
-				"requestBody": map[string]interface{}{
-					"name": map[string]interface{}{"type": "string"},
-				},
-			},
-			wantBool:   false,
-			wantFields: nil,
-		},
-		{
-			name:       "no requestBody",
-			method:     map[string]interface{}{},
-			wantBool:   false,
-			wantFields: nil,
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got, names := hasFileFields(tt.method)
-			if got != tt.wantBool {
-				t.Errorf("hasFileFields() = %v, want %v", got, tt.wantBool)
-			}
-			if tt.wantFields == nil && names != nil {
-				t.Errorf("expected nil names, got %v", names)
-			}
-			if tt.wantFields != nil && len(names) != len(tt.wantFields) {
-				t.Errorf("expected %d field names, got %d", len(tt.wantFields), len(names))
-			}
-		})
-	}
-}
-
-func TestCompleteSchemaPathForSpec(t *testing.T) {
-	resources := map[string]interface{}{
-		"records": map[string]interface{}{
-			"methods": map[string]interface{}{
-				"create": map[string]interface{}{},
-				"list":   map[string]interface{}{},
-			},
-		},
-		"record_permissions": map[string]interface{}{
-			"methods": map[string]interface{}{
-				"get": map[string]interface{}{},
-			},
-		},
-	}
-
-	got := completeSchemaPathForSpec("base", resources, "records.cr")
-	if len(got) != 1 || got[0] != "base.records.create" {
-		t.Fatalf("completions = %v, want [base.records.create]", got)
-	}
-
-	got = completeSchemaPathForSpec("base", resources, "record")
-	if len(got) != 2 || got[0] != "base.record_permissions." || got[1] != "base.records." {
-		t.Fatalf("resource completions = %v", got)
-	}
-}
-
-func TestFilterSpecByStrictMode_RemovesIncompatibleMethodsFromCompletionSource(t *testing.T) {
-	spec := map[string]interface{}{
-		"resources": map[string]interface{}{
-			"records": map[string]interface{}{
-				"methods": map[string]interface{}{
-					"list":   map[string]interface{}{"accessTokens": []interface{}{"tenant"}},
-					"create": map[string]interface{}{"accessTokens": []interface{}{"user"}},
-				},
-			},
-		},
-	}
-
-	filtered := filterSpecByStrictMode(spec, core.StrictModeBot)
-	resources, _ := filtered["resources"].(map[string]interface{})
-	got := completeSchemaPathForSpec("base", resources, "records.")
-	if len(got) != 1 || got[0] != "base.records.list" {
-		t.Fatalf("filtered completions = %v, want [base.records.list]", got)
-	}
-}
+// Completion candidate generation (dotted + space forms, strict-mode filtering,
+// dotted-resource handling) now lives in internal/apicatalog and is covered by
+// apicatalog's TestComplete. cmd/schema only adapts catalog.Complete to cobra.