feat(drive): add +folder-permission-get shortcut

shortcuts/drive/drive_folder_permission_get.go

@@ -0,0 +1,153 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+type driveFolderPermissionGetSpec struct {
+	FolderToken string
+}
+
+func readDriveFolderPermissionGetSpec(runtime *common.RuntimeContext) (driveFolderPermissionGetSpec, error) {
+	rawURL := strings.TrimSpace(runtime.Str("url"))
+	rawToken := strings.TrimSpace(runtime.Str("folder-token"))
+
+	if rawURL == "" && rawToken == "" {
+		return driveFolderPermissionGetSpec{}, errs.NewValidationError(
+			errs.SubtypeInvalidArgument,
+			"pass exactly one of --url or --folder-token",
+		).WithParam("--url")
+	}
+	if rawURL != "" && rawToken != "" {
+		return driveFolderPermissionGetSpec{}, errs.NewValidationError(
+			errs.SubtypeInvalidArgument,
+			"--url and --folder-token are mutually exclusive; pass only one folder locator",
+		).WithParam("--url")
+	}
+
+	if rawToken != "" {
+		if err := validate.ResourceName(rawToken, "--folder-token"); err != nil {
+			return driveFolderPermissionGetSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--folder-token")
+		}
+		return driveFolderPermissionGetSpec{FolderToken: rawToken}, nil
+	}
+
+	ref, ok := common.ParseResourceURL(rawURL)
+	if !ok {
+		return driveFolderPermissionGetSpec{}, errs.NewValidationError(
+			errs.SubtypeInvalidArgument,
+			"unsupported --url %q: pass a recognized Lark Drive folder URL such as https://example.feishu.cn/drive/folder/<folder_token>",
+			rawURL,
+		).WithParam("--url")
+	}
+	if ref.Type != "folder" {
+		return driveFolderPermissionGetSpec{}, errs.NewValidationError(
+			errs.SubtypeInvalidArgument,
+			"--url must point to a Drive folder; got resource type %q",
+			ref.Type,
+		).WithParam("--url")
+	}
+	if err := validate.ResourceName(ref.Token, "--url"); err != nil {
+		return driveFolderPermissionGetSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--url")
+	}
+	return driveFolderPermissionGetSpec{FolderToken: ref.Token}, nil
+}
+
+func (s driveFolderPermissionGetSpec) url(runtime *common.RuntimeContext) string {
+	if runtime != nil && runtime.Config != nil {
+		if u := common.BuildResourceURL(runtime.Config.Brand, "folder", s.FolderToken); u != "" {
+			return u
+		}
+	}
+	return common.BuildResourceURL("", "folder", s.FolderToken)
+}
+
+func (s driveFolderPermissionGetSpec) params() map[string]interface{} {
+	return map[string]interface{}{"type": "folder"}
+}
+
+func (s driveFolderPermissionGetSpec) apiPath() string {
+	return drivePermissionPublicV2Path(s.FolderToken)
+}
+
+func drivePermissionPublicV2Path(token string) string {
+	return fmt.Sprintf("/open-apis/drive/v2/permissions/%s/public", validate.EncodePathSegment(token))
+}
+
+func (s driveFolderPermissionGetSpec) output(runtime *common.RuntimeContext, data map[string]interface{}) map[string]interface{} {
+	permissionPublic := interface{}(data)
+	if nestedPermissionPublic := common.GetMap(data, "permission_public"); nestedPermissionPublic != nil {
+		permissionPublic = nestedPermissionPublic
+	}
+	return map[string]interface{}{
+		"permission_public": permissionPublic,
+	}
+}
+
+// DriveFolderPermissionGet queries the permission_public settings for a Drive
+// folder itself.
+var DriveFolderPermissionGet = common.Shortcut{
+	Service:     "drive",
+	Command:     "+folder-permission-get",
+	Description: "Get a Drive folder's sharing, copy, download, and comment permission settings",
+	Risk:        "read",
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "url", Desc: "Drive folder URL, for example https://example.feishu.cn/drive/folder/<folder_token>"},
+		{Name: "folder-token", Desc: "Drive folder token; mutually exclusive with --url"},
+	},
+	Tips: []string{
+		"Pass exactly one of --url or --folder-token.",
+		"This shortcut reads the folder's own permission settings; it does not list child document permissions.",
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := readDriveFolderPermissionGetSpec(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		spec, err := readDriveFolderPermissionGetSpec(runtime)
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		return common.NewDryRunAPI().
+			Desc("Get Drive folder permission settings").
+			GET(spec.apiPath()).
+			Params(spec.params())
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		spec, err := readDriveFolderPermissionGetSpec(runtime)
+		if err != nil {
+			return err
+		}
+
+		fmt.Fprintf(runtime.IO().ErrOut, "Getting permission settings for folder %s...\n", common.MaskToken(spec.FolderToken))
+		data, err := runtime.CallAPITyped(
+			"GET",
+			spec.apiPath(),
+			spec.params(),
+			nil,
+		)
+		if err != nil {
+			return err
+		}
+
+		out := spec.output(runtime, data)
+		runtime.OutFormat(out, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "Type:         folder\n")
+			fmt.Fprintf(w, "FolderToken:  %s\n", spec.FolderToken)
+			fmt.Fprintf(w, "URL:          %s\n", spec.url(runtime))
+		})
+		return nil
+	},
+}

shortcuts/drive/drive_folder_permission_get_test.go

@@ -0,0 +1,221 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func newDriveFolderPermissionGetRuntime(t *testing.T, rawURL, folderToken string) *common.RuntimeContext {
+	t.Helper()
+
+	cmd := &cobra.Command{Use: "drive +folder-permission-get"}
+	cmd.Flags().String("url", "", "")
+	cmd.Flags().String("folder-token", "", "")
+	if rawURL != "" {
+		if err := cmd.Flags().Set("url", rawURL); err != nil {
+			t.Fatalf("set --url: %v", err)
+		}
+	}
+	if folderToken != "" {
+		if err := cmd.Flags().Set("folder-token", folderToken); err != nil {
+			t.Fatalf("set --folder-token: %v", err)
+		}
+	}
+	return common.TestNewRuntimeContext(cmd, driveTestConfig())
+}
+
+func TestDriveFolderPermissionGetSpecResolvesFolderURL(t *testing.T) {
+	t.Parallel()
+
+	runtime := newDriveFolderPermissionGetRuntime(t, "https://example.feishu.cn/drive/folder/fldTok?from=share", "")
+	spec, err := readDriveFolderPermissionGetSpec(runtime)
+	if err != nil {
+		t.Fatalf("read spec: %v", err)
+	}
+	if spec.FolderToken != "fldTok" {
+		t.Fatalf("FolderToken = %q, want fldTok", spec.FolderToken)
+	}
+}
+
+func TestDriveFolderPermissionGetSpecResolvesBareFolderToken(t *testing.T) {
+	t.Parallel()
+
+	runtime := newDriveFolderPermissionGetRuntime(t, "", " fldTok ")
+	spec, err := readDriveFolderPermissionGetSpec(runtime)
+	if err != nil {
+		t.Fatalf("read spec: %v", err)
+	}
+	if spec.FolderToken != "fldTok" {
+		t.Fatalf("FolderToken = %q, want fldTok", spec.FolderToken)
+	}
+}
+
+func TestDriveFolderPermissionGetSpecValidationErrorsAreTyped(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name        string
+		rawURL      string
+		folderToken string
+		wantParam   string
+		wantMessage string
+	}{
+		{
+			name:        "missing locator",
+			wantParam:   "--url",
+			wantMessage: "pass exactly one",
+		},
+		{
+			name:        "mutually exclusive locators",
+			rawURL:      "https://example.feishu.cn/drive/folder/fldTok",
+			folderToken: "fldTok",
+			wantParam:   "--url",
+			wantMessage: "mutually exclusive",
+		},
+		{
+			name:        "non-folder URL",
+			rawURL:      "https://example.feishu.cn/docx/doxTok",
+			wantParam:   "--url",
+			wantMessage: "must point to a Drive folder",
+		},
+		{
+			name:        "unsupported URL",
+			rawURL:      "https://example.feishu.cn/calendar/calTok",
+			wantParam:   "--url",
+			wantMessage: "unsupported --url",
+		},
+		{
+			name:        "invalid bare folder token",
+			folderToken: "../bad",
+			wantParam:   "--folder-token",
+			wantMessage: "--folder-token",
+		},
+	}
+
+	for _, temp := range tests {
+		tt := temp
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			runtime := newDriveFolderPermissionGetRuntime(t, tt.rawURL, tt.folderToken)
+			_, err := readDriveFolderPermissionGetSpec(runtime)
+			if err == nil {
+				t.Fatal("expected validation error, got nil")
+			}
+			problem, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("error is not typed: %T %v", err, err)
+			}
+			if problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument {
+				t.Fatalf("problem = %s/%s, want validation/invalid_argument", problem.Category, problem.Subtype)
+			}
+			if validationErr, ok := err.(*errs.ValidationError); ok {
+				if validationErr.Param != tt.wantParam {
+					t.Fatalf("param = %q, want %q", validationErr.Param, tt.wantParam)
+				}
+			} else {
+				t.Fatalf("error type = %T, want *errs.ValidationError", err)
+			}
+			if !strings.Contains(err.Error(), tt.wantMessage) {
+				t.Fatalf("error = %q, want substring %q", err.Error(), tt.wantMessage)
+			}
+		})
+	}
+}
+
+func TestDriveFolderPermissionGetDryRunIncludesGETRequest(t *testing.T) {
+	t.Parallel()
+
+	runtime := newDriveFolderPermissionGetRuntime(t, "https://example.feishu.cn/drive/folder/fldTok", "")
+	dry := DriveFolderPermissionGet.DryRun(context.Background(), runtime)
+	if dry == nil {
+		t.Fatal("DryRun returned nil")
+	}
+	data, err := json.Marshal(dry)
+	if err != nil {
+		t.Fatalf("marshal dry-run: %v", err)
+	}
+	out := string(data)
+	for _, want := range []string{
+		`"/open-apis/drive/v2/permissions/fldTok/public"`,
+		`"GET"`,
+		`"type":"folder"`,
+	} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("dry-run output missing %q:\n%s", want, out)
+		}
+	}
+	if strings.Contains(out, `"folder_token"`) {
+		t.Fatalf("dry-run output contains folder_token, want omitted:\n%s", out)
+	}
+}
+
+func TestDriveFolderPermissionGetExecutePreservesPermissionPublic(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v2/permissions/fldTok/public?type=folder",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"permission_public": map[string]interface{}{
+					"link_share_entity":          "closed",
+					"external_access_entity":     "closed",
+					"security_entity":            "anyone_can_view",
+					"comment_entity":             "anyone_can_view",
+					"share_entity":               "anyone",
+					"manage_collaborator_entity": "collaborator_can_view",
+					"lock_switch":                false,
+					"server_future_folder_field": "preserved",
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveFolderPermissionGet, []string{
+		"+folder-permission-get",
+		"--folder-token", "fldTok",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	for _, key := range []string{"type", "folder_token", "url"} {
+		if _, ok := data[key]; ok {
+			t.Fatalf("data[%s] = %#v, want field omitted", key, data[key])
+		}
+	}
+	permissionPublic, _ := data["permission_public"].(map[string]interface{})
+	if permissionPublic == nil {
+		t.Fatalf("permission_public missing in output: %#v", data)
+	}
+	for key, want := range map[string]interface{}{
+		"link_share_entity":          "closed",
+		"external_access_entity":     "closed",
+		"security_entity":            "anyone_can_view",
+		"comment_entity":             "anyone_can_view",
+		"share_entity":               "anyone",
+		"manage_collaborator_entity": "collaborator_can_view",
+		"lock_switch":                false,
+		"server_future_folder_field": "preserved",
+	} {
+		if permissionPublic[key] != want {
+			t.Fatalf("permission_public[%s] = %#v, want %#v", key, permissionPublic[key], want)
+		}
+	}
+}

shortcuts/drive/shortcuts.go

@@ -31,6 +31,7 @@ func Shortcuts() []common.Shortcut {
 		DriveTaskResult,
 		DriveApplyPermission,
 		DriveMemberAdd,
+		DriveFolderPermissionGet,
 		DriveSecureLabelList,
 		DriveSecureLabelUpdate,
 		DriveSearch,

shortcuts/drive/shortcuts_test.go

@@ -37,6 +37,7 @@ func TestShortcutsIncludesExpectedCommands(t *testing.T) {
 		"+task_result",
 		"+apply-permission",
 		"+member-add",
+		"+folder-permission-get",
 		"+secure-label-list",
 		"+secure-label-update",
 		"+search",