feat(okr,whiteboard): emit typed error envelopes across both domains

The okr and whiteboard commands now report every failure as a typed error
envelope. Invalid flags, malformed input, output-file conflicts, and API or
transport failures alike carry a stable category, subtype, the offending flag
or Lark error code, and a meaningful exit code — so scripts and agents can
branch on the error shape instead of scraping message strings.

Author: evandance

.golangci.yml

@@ -65,20 +65,20 @@ linters:
           - forbidigo
       # errs-typed-only enforced on paths already migrated to errs.NewXxxError.
       # Add a path when its migration is complete.
-      - path-except: (internal/auth/|internal/errcompat/|internal/errclass/|internal/client/|internal/cmdutil/factory\.go|cmd/auth/|cmd/config/|cmd/service/|shortcuts/common/mcp_client\.go|shortcuts/calendar/helpers\.go|shortcuts/drive/)
+      - path-except: (internal/auth/|internal/errcompat/|internal/errclass/|internal/client/|internal/cmdutil/factory\.go|cmd/auth/|cmd/config/|cmd/service/|shortcuts/common/mcp_client\.go|shortcuts/calendar/helpers\.go|shortcuts/drive/|shortcuts/okr/|shortcuts/whiteboard/)
         text: errs-typed-only
         linters:
           - forbidigo
       # errs-no-bare-wrap enforced on paths fully migrated to typed final
       # errors. Scoped separately from errs-typed-only because cmd/auth/,
       # cmd/config/ still have residual fmt.Errorf and must not be caught.
-      - path-except: (shortcuts/drive/|shortcuts/calendar/helpers\.go|shortcuts/common/mcp_client\.go)
+      - path-except: (shortcuts/drive/|shortcuts/okr/|shortcuts/whiteboard/|shortcuts/calendar/helpers\.go|shortcuts/common/mcp_client\.go)
         text: errs-no-bare-wrap
         linters:
           - forbidigo
-      # errs-no-legacy-helper is drive-only: the shared helpers it bans are
-      # still used by other domains until their later migration phase.
-      - path-except: (shortcuts/drive/)
+      # errs-no-legacy-helper bans shared helpers that emit legacy output.Err*
+      # shapes, on domains that have migrated to typed errs.* builders.
+      - path-except: (shortcuts/drive/|shortcuts/okr/|shortcuts/whiteboard/)
         text: errs-no-legacy-helper
         linters:
           - forbidigo

shortcuts/okr/okr_cycle_detail.go

@@ -11,8 +11,8 @@ import (
 	"strconv"
 	"time"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
-	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 )
 
 // OKRCycleDetail lists all objectives and their key results under a given OKR cycle.
@@ -30,10 +30,10 @@ var OKRCycleDetail = common.Shortcut{
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		cycleID := runtime.Str("cycle-id")
 		if cycleID == "" {
-			return common.FlagErrorf("--cycle-id is required")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--cycle-id is required").WithParam("--cycle-id")
 		}
 		if id, err := strconv.ParseInt(cycleID, 10, 64); err != nil || id <= 0 {
-			return common.FlagErrorf("--cycle-id must be a positive int64")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--cycle-id must be a positive int64").WithParam("--cycle-id")
 		}
 		return nil
 	},
@@ -52,8 +52,7 @@ var OKRCycleDetail = common.Shortcut{
 		cycleID := runtime.Str("cycle-id")
 
 		// Paginate objectives under the cycle.
-		queryParams := make(larkcore.QueryParams)
-		queryParams.Set("page_size", "100")
+		queryParams := map[string]interface{}{"page_size": "100"}
 
 		var objectives []Objective
 		page := 0
@@ -71,7 +70,7 @@ var OKRCycleDetail = common.Shortcut{
 			page++
 
 			path := fmt.Sprintf("/open-apis/okr/v2/cycles/%s/objectives", cycleID)
-			data, err := runtime.DoAPIJSON("GET", path, queryParams, nil)
+			data, err := runtime.CallAPITyped("GET", path, queryParams, nil)
 			if err != nil {
 				return err
 			}
@@ -93,7 +92,7 @@ var OKRCycleDetail = common.Shortcut{
 			if !hasMore || pageToken == "" {
 				break
 			}
-			queryParams.Set("page_token", pageToken)
+			queryParams["page_token"] = pageToken
 		}
 
 		// For each objective, paginate key results and convert to response format.
@@ -104,8 +103,7 @@ var OKRCycleDetail = common.Shortcut{
 			}
 			obj := &objectives[i]
 
-			krQuery := make(larkcore.QueryParams)
-			krQuery.Set("page_size", "100")
+			krQuery := map[string]interface{}{"page_size": "100"}
 
 			var keyResults []KeyResult
 			krPage := 0
@@ -123,7 +121,7 @@ var OKRCycleDetail = common.Shortcut{
 				krPage++
 
 				path := fmt.Sprintf("/open-apis/okr/v2/objectives/%s/key_results", obj.ID)
-				data, err := runtime.DoAPIJSON("GET", path, krQuery, nil)
+				data, err := runtime.CallAPITyped("GET", path, krQuery, nil)
 				if err != nil {
 					return err
 				}
@@ -145,7 +143,7 @@ var OKRCycleDetail = common.Shortcut{
 				if !hasMore || pageToken == "" {
 					break
 				}
-				krQuery.Set("page_token", pageToken)
+				krQuery["page_token"] = pageToken
 			}
 
 			respObj := obj.ToResp()

shortcuts/okr/okr_cycle_detail_test.go

@@ -6,11 +6,13 @@ package okr
 import (
 	"bytes"
 	"encoding/json"
+	"errors"
 	"strings"
 	"testing"
 
 	"github.com/spf13/cobra"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
@@ -106,6 +108,31 @@ func TestCycleDetailValidate_InvalidCycleID_Negative(t *testing.T) {
 	}
 }
 
+// TestCycleDetailValidate_TypedError locks the typed-envelope contract shared by
+// every okr flag check: an invalid flag surfaces as *errs.ValidationError carrying
+// SubtypeInvalidArgument and the offending --flag (readable via errors.As /
+// errs.ProblemOf), and maps to the validation exit code rather than a legacy api error.
+func TestCycleDetailValidate_TypedError(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, cycleDetailTestConfig(t))
+	err := runCycleDetailShortcut(t, f, stdout, []string{"+cycle-detail", "--cycle-id", "0"})
+
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("error is not *errs.ValidationError: %T (%v)", err, err)
+	}
+	if ve.Subtype != errs.SubtypeInvalidArgument {
+		t.Errorf("Subtype = %q, want %q", ve.Subtype, errs.SubtypeInvalidArgument)
+	}
+	if ve.Param != "--cycle-id" {
+		t.Errorf("Param = %q, want %q", ve.Param, "--cycle-id")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok || p.Category != errs.CategoryValidation {
+		t.Errorf("ProblemOf category = %v (ok=%v), want %q", p, ok, errs.CategoryValidation)
+	}
+}
+
 func TestCycleDetailValidate_ValidCycleID(t *testing.T) {
 	t.Parallel()
 	f, stdout, _, reg := cmdutil.TestFactory(t, cycleDetailTestConfig(t))

shortcuts/okr/okr_cycle_list.go

@@ -12,30 +12,30 @@ import (
 	"strings"
 	"time"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
-	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 )
 
 // parseTimeRange parses a "YYYY-MM--YYYY-MM" string into two time.Time values.
 // The start is the first moment of the start month; the end is the last moment of the end month.
 func parseTimeRange(s string) (start, end time.Time, err error) {
 	parts := strings.SplitN(s, "--", 2)
 	if len(parts) != 2 {
-		return time.Time{}, time.Time{}, fmt.Errorf("invalid time-range format %q, expected YYYY-MM--YYYY-MM", s)
+		return time.Time{}, time.Time{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --time-range format %q, expected YYYY-MM--YYYY-MM", s).WithParam("--time-range")
 	}
 	start, err = time.Parse("2006-01", strings.TrimSpace(parts[0]))
 	if err != nil {
-		return time.Time{}, time.Time{}, fmt.Errorf("invalid start month %q: %w", parts[0], err)
+		return time.Time{}, time.Time{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --time-range start month %q: %v", parts[0], err).WithParam("--time-range").WithCause(err)
 	}
 	end, err = time.Parse("2006-01", strings.TrimSpace(parts[1]))
 	if err != nil {
-		return time.Time{}, time.Time{}, fmt.Errorf("invalid end month %q: %w", parts[1], err)
+		return time.Time{}, time.Time{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --time-range end month %q: %v", parts[1], err).WithParam("--time-range").WithCause(err)
 	}
 	// end is the last moment of the end month
 	end = end.AddDate(0, 1, 0).Add(-time.Millisecond)
 	if start.After(end) {
-		return time.Time{}, time.Time{}, fmt.Errorf("start month %s is after end month %s", parts[0], parts[1])
+		return time.Time{}, time.Time{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --time-range: start month %s is after end month %s", parts[0], parts[1]).WithParam("--time-range")
 	}
 	return start, end, nil
 }
@@ -69,7 +69,7 @@ var OKRListCycles = common.Shortcut{
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		idType := runtime.Str("user-id-type")
 		if idType != "open_id" && idType != "union_id" && idType != "user_id" {
-			return common.FlagErrorf("--user-id-type must be one of: open_id | union_id | user_id")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--user-id-type must be one of: open_id | union_id | user_id").WithParam("--user-id-type")
 		}
 		userID := runtime.Str("user-id")
 		if err := validate.RejectControlChars(userID, "user-id"); err != nil {
@@ -82,7 +82,7 @@ var OKRListCycles = common.Shortcut{
 				return err
 			}
 			if _, _, err := parseTimeRange(tr); err != nil {
-				return common.FlagErrorf("--time-range: %s", err)
+				return err
 			}
 		}
 		return nil
@@ -110,16 +110,17 @@ var OKRListCycles = common.Shortcut{
 			var err error
 			rangeStart, rangeEnd, err = parseTimeRange(timeRange)
 			if err != nil {
-				return common.FlagErrorf("--time-range: %s", err)
+				return err
 			}
 			hasRange = true
 		}
 
 		// Paginated fetch of all cycles
-		queryParams := make(larkcore.QueryParams)
-		queryParams.Set("user_id", userID)
-		queryParams.Set("user_id_type", userIDType)
-		queryParams.Set("page_size", "100")
+		queryParams := map[string]interface{}{
+			"user_id":      userID,
+			"user_id_type": userIDType,
+			"page_size":    "100",
+		}
 
 		var allCycles []Cycle
 		page := 0
@@ -136,7 +137,7 @@ var OKRListCycles = common.Shortcut{
 			}
 			page++
 
-			data, err := runtime.DoAPIJSON("GET", "/open-apis/okr/v2/cycles", queryParams, nil)
+			data, err := runtime.CallAPITyped("GET", "/open-apis/okr/v2/cycles", queryParams, nil)
 			if err != nil {
 				return err
 			}
@@ -158,7 +159,7 @@ var OKRListCycles = common.Shortcut{
 			if !hasMore || pageToken == "" {
 				break
 			}
-			queryParams.Set("page_token", pageToken)
+			queryParams["page_token"] = pageToken
 		}
 
 		// Filter by time-range overlap

shortcuts/okr/okr_errors.go

@@ -0,0 +1,34 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package okr
+
+import (
+	"errors"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/extension/fileio"
+)
+
+// okrInputStatError maps a FileIO.Stat/Open error for input file validation to
+// a typed validation error: path validation failures read as "unsafe file
+// path", other errors as "cannot read file".
+func okrInputStatError(err error) error {
+	if err == nil {
+		return nil
+	}
+	if errors.Is(err, fileio.ErrPathValidation) {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe file path: %s", err).WithCause(err)
+	}
+	return errs.NewValidationError(errs.SubtypeInvalidArgument, "cannot read file: %s", err).WithCause(err)
+}
+
+// wrapOkrNetworkErr returns err unchanged when it is already a typed errs.*
+// error (preserving subtype / code / log_id from the runtime boundary) and only
+// wraps a raw, unclassified error as a transport-level network error.
+func wrapOkrNetworkErr(err error, format string, args ...any) error {
+	if _, ok := errs.ProblemOf(err); ok {
+		return err
+	}
+	return errs.NewNetworkError(errs.SubtypeNetworkTransport, format, args...).WithCause(err)
+}

shortcuts/okr/okr_image_upload.go

@@ -5,7 +5,6 @@ package okr
 
 import (
 	"context"
-	"encoding/json"
 	"errors"
 	"fmt"
 	"path/filepath"
@@ -14,6 +13,7 @@ import (
 
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -43,24 +43,24 @@ var OKRUploadImage = common.Shortcut{
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		filePath := runtime.Str("file")
 		if filePath == "" {
-			return common.FlagErrorf("--file is required")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file is required").WithParam("--file")
 		}
 		ext := strings.ToLower(filepath.Ext(filePath))
 		if !allowedImageExts[ext] {
-			return common.FlagErrorf("--file must be an image (supported: JPG, JPEG, PNG, GIF, BMP), got %q", ext)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file must be an image (supported: JPG, JPEG, PNG, GIF, BMP), got %q", ext).WithParam("--file")
 		}
 
 		targetID := runtime.Str("target-id")
 		if targetID == "" {
-			return common.FlagErrorf("--target-id is required")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--target-id is required").WithParam("--target-id")
 		}
 		if id, err := strconv.ParseInt(targetID, 10, 64); err != nil || id <= 0 {
-			return common.FlagErrorf("--target-id must be a positive int64")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--target-id must be a positive int64").WithParam("--target-id")
 		}
 
 		targetType := runtime.Str("target-type")
 		if _, ok := targetTypeAllowed[targetType]; !ok {
-			return common.FlagErrorf("--target-type must be one of: objective | key_result")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--target-type must be one of: objective | key_result").WithParam("--target-type")
 		}
 		return nil
 	},
@@ -87,12 +87,12 @@ var OKRUploadImage = common.Shortcut{
 
 		info, err := runtime.FileIO().Stat(filePath)
 		if err != nil {
-			return common.WrapInputStatError(err)
+			return okrInputStatError(err)
 		}
 
 		f, err := runtime.FileIO().Open(filePath)
 		if err != nil {
-			return common.WrapInputStatError(err)
+			return okrInputStatError(err)
 		}
 		defer f.Close()
 
@@ -114,26 +114,19 @@ var OKRUploadImage = common.Shortcut{
 			if errors.As(err, &exitErr) {
 				return err
 			}
-			return output.ErrNetwork("upload failed: %v", err)
+			return wrapOkrNetworkErr(err, "upload failed: %v", err)
 		}
 
-		var result map[string]interface{}
-		if err := json.Unmarshal(apiResp.RawBody, &result); err != nil {
-			return output.Errorf(output.ExitAPI, "api_error", "upload failed: invalid response JSON: %v", err)
-		}
-
-		if larkCode := int(common.GetFloat(result, "code")); larkCode != 0 {
-			msg, _ := result["msg"].(string)
-			return output.ErrAPI(larkCode, fmt.Sprintf("upload failed: [%d] %s", larkCode, msg), result["error"])
+		data, err := runtime.ClassifyAPIResponse(apiResp)
+		if err != nil {
+			return err
 		}
 
-		data, _ := result["data"].(map[string]interface{})
-		fileToken, _ := data["file_token"].(string)
-		url, _ := data["url"].(string)
-
+		fileToken := common.GetString(data, "file_token")
 		if fileToken == "" {
-			return output.Errorf(output.ExitAPI, "api_error", "upload failed: no file_token returned")
+			return errs.NewInternalError(errs.SubtypeInvalidResponse, "upload failed: no file_token returned")
 		}
+		url := common.GetString(data, "url")
 
 		runtime.Out(map[string]interface{}{
 			"file_token": fileToken,