refactor: converge command pipelines onto a typed metadata model + catalog

Extract the metadata logic duplicated across schema/cmdutil/registry into
two new single-purpose modules and thin the command layer to adapters over
them — net -924 lines of behavior-preserving moves and de-duplication, plus
a few agent-facing additions and fixes found along the way.

Moved / de-duplicated
- New internal/meta: typed model over meta_data.json. Absorbs field-value
  normalization and the access-token<->identity bijection previously split
  across schema.convertAccessTokens, cmdutil.AccessTokensToIdentities and
  registry.IdentityToAccessToken — three duplicate token interpreters
  collapsed into one (cmdutil identity/risk/fileupload now defer to it).
- New internal/apicatalog: navigation over the typed model. Path resolution
  moved here (internal/schema/path.go -> internal/apicatalog/path.go); the
  resolve<->walk round-trip is closed for nested resources.
- internal/schema is now render-only — dropped its cmdutil and registry
  imports; risk-level constants moved to the new internal/core/risk.go.
- internal/registry keeps only source adapter + scope policy; its scope
  collectors and cmd/service registration now walk the catalog instead of
  hand-rolling traversal. cmd/service param-flag handling extracted into
  paramflags.go/flaggroups.go and no longer imports schema.

New (agent-facing)
- Typed flags for raw API commands; grouped --help by input kind with inline
  enum value=meaning and method affordance in Long help; envelope carries
  enumDescriptions (parallel to enum) for per-value meanings.

Fixed (found during the convergence)
- meta.Option.Value is tolerant `any` and already-typed literals normalize to
  the canonical type, so one bad option value can't blank the whole catalog
  and numeric enums sort correctly.
- nested-resource descent extended to completion; auth-hint resolves the
  nested catalog path instead of a hard-coded depth.

Removed
- The byte-for-byte envelope golden: it snapshotted metadata fetched at build
  time, baking real API data into git with no way to desensitize (CI
  regenerates from fresh real data and compares exactly). Assembler logic is
  covered on synthetic data instead.

Behavior preserved: public command tree/paths, request planning, pagination,
dry-run, confirmation. Typed enum flags are documentation, not hard-validated.

Change-Id: I2d6c5127a9e76955fb467a45557ae155299a2660

Author: liangshuo-1

cmd/auth/login_interactive.go

@@ -92,16 +92,11 @@ func buildDomainMeta(name, lang string) domainMeta {
 			Description: desc,
 		}
 	}
-	// Fallback: read from from_meta spec (legacy)
-	meta := registry.LoadFromMeta(name)
+	// Fallback: read from the typed service spec (legacy)
 	dm := domainMeta{Name: name}
-	if meta != nil {
-		if t, ok := meta["title"].(string); ok {
-			dm.Title = t
-		}
-		if d, ok := meta["description"].(string); ok {
-			dm.Description = d
-		}
+	if svc, ok := registry.ServiceTyped(name); ok {
+		dm.Title = svc.Title
+		dm.Description = svc.Description
 	}
 	return dm
 }

cmd/command_catalog_path_test.go

@@ -0,0 +1,52 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+// TestCommandCatalogPath pins that the auth-hint path reconstruction inverts the
+// service command tree for any depth — flat dotted resources AND genuinely
+// nested resources — so it round-trips through apicatalog.Resolve instead of
+// assuming a fixed root->service->resource->method shape.
+func TestCommandCatalogPath(t *testing.T) {
+	chain := func(names ...string) *cobra.Command {
+		var parent, leaf *cobra.Command
+		for _, n := range names {
+			c := &cobra.Command{Use: n}
+			if parent != nil {
+				parent.AddCommand(c)
+			}
+			parent = c
+			leaf = c
+		}
+		return leaf
+	}
+
+	tests := []struct {
+		name string
+		leaf *cobra.Command
+		want []string
+	}{
+		{"flat dotted resource", chain("lark-cli", "im", "chat.members", "create"), []string{"im", "chat.members", "create"}},
+		{"nested resources", chain("lark-cli", "im", "spaces", "items", "get"), []string{"im", "spaces", "items", "get"}},
+		{"service level", chain("lark-cli", "im"), []string{"im"}},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := commandCatalogPath(tt.leaf); !reflect.DeepEqual(got, tt.want) {
+				t.Errorf("commandCatalogPath = %v, want %v", got, tt.want)
+			}
+		})
+	}
+
+	// The root command (no parent) has no catalog path.
+	if got := commandCatalogPath(&cobra.Command{Use: "lark-cli"}); len(got) != 0 {
+		t.Errorf("root path = %v, want empty", got)
+	}
+}

cmd/error_auth_hint.go

@@ -11,6 +11,7 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/apicatalog"
 	internalauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
@@ -118,38 +119,37 @@ func resolveDeclaredShortcutScopes(cmd *cobra.Command, identity string) []string
 }
 
 // resolveDeclaredServiceMethodScopes returns the scopes declared by a
-// service/resource/method command from the embedded from_meta registry.
+// service/resource/method command. It reconstructs the catalog path from the
+// command ancestry and resolves it through the same navigation Module the
+// command tree is built from (apicatalog), so it stays correct for nested
+// resources instead of hard-coding a root->service->resource->method depth.
+// Non-method commands (services, resources, shortcuts) resolve to a non-method
+// target and yield no scopes.
 func resolveDeclaredServiceMethodScopes(cmd *cobra.Command, identity string) []string {
-	// Service-method scope lookup only applies to commands mounted as
-	// root -> service -> resource -> method. Non-resource/method commands
-	// intentionally return no scopes here so auth-hint enrichment does not
-	// change runtime semantics for other command shapes.
-	if cmd == nil || cmd.Parent() == nil || cmd.Parent().Parent() == nil || cmd.Parent().Parent().Parent() == nil {
+	if cmd == nil || strings.HasPrefix(cmd.Name(), "+") {
 		return nil
 	}
-	if strings.HasPrefix(cmd.Name(), "+") {
+	path := commandCatalogPath(cmd)
+	if len(path) == 0 {
 		return nil
 	}
-
-	service := cmd.Parent().Parent().Name()
-	resource := cmd.Parent().Name()
-	method := cmd.Name()
-
-	spec := registry.LoadFromMeta(service)
-	if spec == nil {
-		return nil
-	}
-	resources, _ := spec["resources"].(map[string]interface{})
-	resMap, _ := resources[resource].(map[string]interface{})
-	if resMap == nil {
+	target, err := registry.RuntimeCatalog().Resolve(path)
+	if err != nil || target.Kind != apicatalog.TargetMethod {
 		return nil
 	}
-	methods, _ := resMap["methods"].(map[string]interface{})
-	methodMap, _ := methods[method].(map[string]interface{})
-	if methodMap == nil {
-		return nil
-	}
-	return registry.DeclaredScopesForMethod(methodMap, identity)
+	return registry.DeclaredScopesForMethod(target.Method.Method, identity)
+}
+
+// commandCatalogPath reconstructs the catalog path [service, resource..., method]
+// from a command's ancestry, excluding the root command. It is the inverse of
+// the service command tree's construction, so any depth (flat or nested)
+// round-trips through apicatalog.Resolve.
+func commandCatalogPath(cmd *cobra.Command) []string {
+	var path []string
+	for c := cmd; c != nil && c.Parent() != nil; c = c.Parent() {
+		path = append([]string{c.Name()}, path...)
+	}
+	return path
 }
 
 // shortcutSupportsIdentity reports whether a shortcut supports the requested

cmd/root.go

@@ -33,7 +33,7 @@ const rootLong = `lark-cli — Lark/Feishu CLI tool.
 USAGE:
     lark-cli <command> [subcommand] [method] [options]
     lark-cli api <method> <path> [--params <json>] [--data <json>]
-    lark-cli schema <service.resource.method> [--format pretty]
+    lark-cli schema <service.resource.method>
 
 EXAMPLES:
     # View upcoming events