feat(okr,whiteboard): surface input errors as typed error envelopes

Invalid flags, malformed input payloads, and output-file conflicts in the
okr and whiteboard commands now return structured error envelopes — each
carrying a stable category, subtype, and the offending flag — instead of
flat strings. Scripts and agents can branch on the error shape and exit
code rather than scraping messages.

API-response errors in these commands keep the existing envelopes for now;
they convert in a follow-up once the shared typed API path is available.

Author: evandance

shortcuts/okr/okr_cycle_detail.go

@@ -11,6 +11,7 @@ import (
 	"strconv"
 	"time"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 )
@@ -30,10 +31,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
 	},
@@ -71,6 +72,8 @@ var OKRCycleDetail = common.Shortcut{
 			page++
 
 			path := fmt.Sprintf("/open-apis/okr/v2/cycles/%s/objectives", cycleID)
+			// TODO(errs-migrate): switch to runtime.CallAPITyped once the typed API path lands; today the
+			// error is the legacy envelope produced inside the shared common.doAPIJSON helper.
 			data, err := runtime.DoAPIJSON("GET", path, queryParams, nil)
 			if err != nil {
 				return err
@@ -123,6 +126,8 @@ var OKRCycleDetail = common.Shortcut{
 				krPage++
 
 				path := fmt.Sprintf("/open-apis/okr/v2/objectives/%s/key_results", obj.ID)
+				// TODO(errs-migrate): switch to runtime.CallAPITyped once the typed API path lands; today the
+				// error is the legacy envelope produced inside the shared common.doAPIJSON helper.
 				data, err := runtime.DoAPIJSON("GET", path, krQuery, nil)
 				if err != nil {
 					return err

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,6 +12,7 @@ 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"
@@ -69,7 +70,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 +83,7 @@ var OKRListCycles = common.Shortcut{
 				return err
 			}
 			if _, _, err := parseTimeRange(tr); err != nil {
-				return common.FlagErrorf("--time-range: %s", err)
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--time-range: %s", err).WithParam("--time-range")
 			}
 		}
 		return nil
@@ -110,7 +111,7 @@ var OKRListCycles = common.Shortcut{
 			var err error
 			rangeStart, rangeEnd, err = parseTimeRange(timeRange)
 			if err != nil {
-				return common.FlagErrorf("--time-range: %s", err)
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--time-range: %s", err).WithParam("--time-range")
 			}
 			hasRange = true
 		}
@@ -136,6 +137,8 @@ var OKRListCycles = common.Shortcut{
 			}
 			page++
 
+			// TODO(errs-migrate): switch to runtime.CallAPITyped once the typed API path lands; today the
+			// error is the legacy envelope produced inside the shared common.doAPIJSON helper.
 			data, err := runtime.DoAPIJSON("GET", "/open-apis/okr/v2/cycles", queryParams, nil)
 			if err != nil {
 				return err

shortcuts/okr/okr_image_upload.go

@@ -14,6 +14,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 +44,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
 	},
@@ -85,6 +86,12 @@ var OKRUploadImage = common.Shortcut{
 		targetType := runtime.Str("target-type")
 		targetTypeVal := targetTypeAllowed[targetType]
 
+		// TODO(errs-migrate): this whole upload flow is the raw-DoAPI boundary —
+		// migrate it as one atomic unit once the typed API path lands. Replace the call with
+		// runtime.CallAPITyped, turn the *output.ExitError pass-through below
+		// into errs.ProblemOf, and lift the local stat helper to a typed builder.
+		// Until then it keeps the legacy common.WrapInputStatError / output.Err*
+		// envelopes so the API classification is not split across two PRs.
 		info, err := runtime.FileIO().Stat(filePath)
 		if err != nil {
 			return common.WrapInputStatError(err)

shortcuts/okr/okr_progress_create.go

@@ -11,6 +11,7 @@ import (
 	"math"
 	"strconv"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -39,7 +40,7 @@ func parseCreateProgressRecordParams(runtime *common.RuntimeContext) (*createPro
 	content := runtime.Str("content")
 	var cb ContentBlock
 	if err := json.Unmarshal([]byte(content), &cb); err != nil {
-		return nil, common.FlagErrorf("--content must be valid ContentBlock JSON: %s", err)
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content must be valid ContentBlock JSON: %s", err).WithParam("--content")
 	}
 	contentV1 := cb.ToV1()
 
@@ -60,13 +61,13 @@ func parseCreateProgressRecordParams(runtime *common.RuntimeContext) (*createPro
 	if v := runtime.Str("progress-percent"); v != "" {
 		percent, err := strconv.ParseFloat(v, 64)
 		if err != nil || math.IsNaN(percent) || math.IsInf(percent, 0) || percent < -99999999999 || percent > 99999999999 {
-			return nil, common.FlagErrorf("--progress-percent must be a number between -99999999999 and 99999999999")
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--progress-percent must be a number between -99999999999 and 99999999999").WithParam("--progress-percent")
 		}
 		progressRate = &ProgressRateV1{Percent: &percent}
 		if s := runtime.Str("progress-status"); s != "" {
 			status, ok := ParseProgressStatus(s)
 			if !ok {
-				return nil, common.FlagErrorf("--progress-status must be one of: normal | overdue | done")
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--progress-status must be one of: normal | overdue | done").WithParam("--progress-status")
 			}
 			progressRate.Status = int32Ptr(int32(status))
 		}
@@ -105,31 +106,31 @@ var OKRCreateProgressRecord = common.Shortcut{
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		content := runtime.Str("content")
 		if content == "" {
-			return common.FlagErrorf("--content is required")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content is required").WithParam("--content")
 		}
 		if err := validate.RejectControlChars(content, "content"); err != nil {
 			return err
 		}
 		// Validate content is valid JSON and can be parsed as ContentBlock
 		var cb ContentBlock
 		if err := json.Unmarshal([]byte(content), &cb); err != nil {
-			return common.FlagErrorf("--content must be valid ContentBlock JSON: %s", err)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content must be valid ContentBlock JSON: %s", err).WithParam("--content")
 		}
 
 		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 err := validate.RejectControlChars(targetID, "target-id"); err != nil {
 			return err
 		}
 		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")
 		}
 
 		if v := runtime.Str("source-title"); v != "" {
@@ -146,21 +147,21 @@ var OKRCreateProgressRecord = common.Shortcut{
 		if v := runtime.Str("progress-percent"); v != "" {
 			percent, err := strconv.ParseFloat(v, 64)
 			if err != nil || math.IsNaN(percent) || math.IsInf(percent, 0) || percent < -99999999999 || percent > 99999999999 {
-				return common.FlagErrorf("--progress-percent must be a number between -99999999999 and 99999999999")
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--progress-percent must be a number between -99999999999 and 99999999999").WithParam("--progress-percent")
 			}
 		}
 		if v := runtime.Str("progress-status"); v != "" {
 			if _, ok := ParseProgressStatus(v); !ok {
-				return common.FlagErrorf("--progress-status must be one of: normal | overdue | done")
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--progress-status must be one of: normal | overdue | done").WithParam("--progress-status")
 			}
 			if v := runtime.Str("progress-percent"); v == "" {
-				return common.FlagErrorf("--progress-percent must provided with --progress-status")
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--progress-percent must provided with --progress-status").WithParam("--progress-percent")
 			}
 		}
 
 		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")
 		}
 		return nil
 	},
@@ -205,6 +206,8 @@ var OKRCreateProgressRecord = common.Shortcut{
 		queryParams := make(larkcore.QueryParams)
 		queryParams.Set("user_id_type", p.UserIDType)
 
+		// TODO(errs-migrate): switch to runtime.CallAPITyped once the typed API path lands; today the
+		// error is the legacy envelope produced inside the shared common.doAPIJSON helper.
 		data, err := runtime.DoAPIJSON("POST", "/open-apis/okr/v1/progress_records/", queryParams, body)
 		if err != nil {
 			return err

shortcuts/okr/okr_progress_delete.go

@@ -9,6 +9,7 @@ import (
 	"io"
 	"strconv"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 )
@@ -28,10 +29,10 @@ var OKRDeleteProgressRecord = common.Shortcut{
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		progressID := runtime.Str("progress-id")
 		if progressID == "" {
-			return common.FlagErrorf("--progress-id is required")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--progress-id is required").WithParam("--progress-id")
 		}
 		if id, err := strconv.ParseInt(progressID, 10, 64); err != nil || id <= 0 {
-			return common.FlagErrorf("--progress-id must be a positive int64")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--progress-id must be a positive int64").WithParam("--progress-id")
 		}
 		return nil
 	},
@@ -46,6 +47,8 @@ var OKRDeleteProgressRecord = common.Shortcut{
 		progressID := runtime.Str("progress-id")
 
 		path := fmt.Sprintf("/open-apis/okr/v1/progress_records/%s", progressID)
+		// TODO(errs-migrate): switch to runtime.CallAPITyped once the typed API path lands; today the
+		// error is the legacy envelope produced inside the shared common.doAPIJSON helper.
 		_, err := runtime.DoAPIJSON("DELETE", path, larkcore.QueryParams{}, nil)
 		if err != nil {
 			return err

shortcuts/okr/okr_progress_get.go

@@ -10,6 +10,7 @@ import (
 	"io"
 	"strconv"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 )
@@ -30,14 +31,14 @@ var OKRGetProgressRecord = common.Shortcut{
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		progressID := runtime.Str("progress-id")
 		if progressID == "" {
-			return common.FlagErrorf("--progress-id is required")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--progress-id is required").WithParam("--progress-id")
 		}
 		if id, err := strconv.ParseInt(progressID, 10, 64); err != nil || id <= 0 {
-			return common.FlagErrorf("--progress-id must be a positive int64")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--progress-id must be a positive int64").WithParam("--progress-id")
 		}
 		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")
 		}
 		return nil
 	},
@@ -60,6 +61,8 @@ var OKRGetProgressRecord = common.Shortcut{
 		queryParams.Set("user_id_type", userIDType)
 
 		path := fmt.Sprintf("/open-apis/okr/v1/progress_records/%s", progressID)
+		// TODO(errs-migrate): switch to runtime.CallAPITyped once the typed API path lands; today the
+		// error is the legacy envelope produced inside the shared common.doAPIJSON helper.
 		data, err := runtime.DoAPIJSON("GET", path, queryParams, nil)
 		if err != nil {
 			return err