feat(task): emit typed error envelopes across the task domain

Task commands now return structured, typed errors instead of the legacy
exit-code envelope: every failure carries a stable category, subtype, and
recovery hint, so callers can branch on the error class instead of parsing
messages. Exit codes derive from the error category — input validation exits 2,
a permission denial exits 3, other API errors exit 1.

Batch operations (adding tasks to a tasklist, creating a tasklist with tasks)
now report partial failure honestly: the per-item successes and failures stay
on stdout and the command exits non-zero instead of masking failures as a
success.

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/task/)
         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/task/|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/)
+      - path-except: (shortcuts/drive/|shortcuts/task/)
         text: errs-no-legacy-helper
         linters:
           - forbidigo

shortcuts/task/shortcuts.go

@@ -13,9 +13,8 @@ import (
 	"strings"
 	"time"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
-	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 )
 
 func inferTaskMemberType(id string) string {
@@ -107,7 +106,7 @@ func buildTaskCreateBody(runtime *common.RuntimeContext) (map[string]interface{}
 	// Handle generic JSON payload if provided
 	if dataStr := runtime.Str("data"); dataStr != "" {
 		if err := json.Unmarshal([]byte(dataStr), &body); err != nil {
-			return nil, output.ErrValidation("--data must be a valid JSON object: %v", err)
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--data must be a valid JSON object: %v", err).WithParam("--data")
 		}
 	}
 
@@ -143,7 +142,7 @@ func buildTaskCreateBody(runtime *common.RuntimeContext) (map[string]interface{}
 	if dueStr := runtime.Str("due"); dueStr != "" {
 		dueObj, err := parseTaskTime(dueStr)
 		if err != nil {
-			return nil, output.ErrValidation("failed to parse due time: %v", err)
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "failed to parse due time: %v", err).WithParam("--due")
 		}
 		body["due"] = dueObj
 	}
@@ -154,7 +153,7 @@ func buildTaskCreateBody(runtime *common.RuntimeContext) (map[string]interface{}
 
 	summary, _ := body["summary"].(string)
 	if strings.TrimSpace(summary) == "" {
-		return nil, output.ErrValidation("task summary is required")
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "task summary is required").WithParam("--summary")
 	}
 
 	return body, nil
@@ -194,27 +193,11 @@ var CreateTask = common.Shortcut{
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		body, err := buildTaskCreateBody(runtime)
 		if err != nil {
-			return WrapTaskError(ErrCodeTaskInvalidParams, err.Error(), "create task")
-		}
-
-		queryParams := make(larkcore.QueryParams)
-		queryParams.Set("user_id_type", "open_id")
-
-		apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
-			HttpMethod:  http.MethodPost,
-			ApiPath:     "/open-apis/task/v2/tasks",
-			QueryParams: queryParams,
-			Body:        body,
-		})
-
-		var result map[string]interface{}
-		if err == nil {
-			if parseErr := json.Unmarshal(apiResp.RawBody, &result); parseErr != nil {
-				return output.Errorf(output.ExitAPI, "api_error", "failed to parse response: %v", parseErr)
-			}
+			return err
 		}
 
-		data, err := HandleTaskApiResult(result, err, "create task")
+		params := map[string]interface{}{"user_id_type": "open_id"}
+		data, err := callTaskAPITyped(runtime, http.MethodPost, "/open-apis/task/v2/tasks", params, body)
 		if err != nil {
 			return err
 		}

shortcuts/task/task_assign.go

@@ -5,15 +5,13 @@ package task
 
 import (
 	"context"
-	"encoding/json"
 	"fmt"
 	"io"
 	"net/http"
 	"net/url"
 	"strings"
 
-	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
-
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -35,7 +33,7 @@ var AssignTask = common.Shortcut{
 
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if runtime.Str("add") == "" && runtime.Str("remove") == "" {
-			return WrapTaskError(ErrCodeTaskInvalidParams, "must specify either --add or --remove", "validate assign")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "must specify either --add or --remove")
 		}
 		return nil
 	},
@@ -62,28 +60,13 @@ var AssignTask = common.Shortcut{
 
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		taskId := url.PathEscape(runtime.Str("task-id"))
-		queryParams := make(larkcore.QueryParams)
-		queryParams.Set("user_id_type", "open_id")
+		params := map[string]interface{}{"user_id_type": "open_id"}
 
 		var lastData map[string]interface{}
 
 		if addStr := runtime.Str("add"); addStr != "" {
 			body := buildMembersBody(addStr, "assignee", runtime.Str("idempotency-key"))
-			apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
-				HttpMethod:  http.MethodPost,
-				ApiPath:     "/open-apis/task/v2/tasks/" + taskId + "/add_members",
-				QueryParams: queryParams,
-				Body:        body,
-			})
-
-			var result map[string]interface{}
-			if err == nil {
-				if parseErr := json.Unmarshal(apiResp.RawBody, &result); parseErr != nil {
-					return WrapTaskError(ErrCodeTaskInternalError, fmt.Sprintf("failed to parse response: %v", parseErr), "parse add members")
-				}
-			}
-
-			data, err := HandleTaskApiResult(result, err, "add task members")
+			data, err := callTaskAPITyped(runtime, http.MethodPost, "/open-apis/task/v2/tasks/"+taskId+"/add_members", params, body)
 			if err != nil {
 				return err
 			}
@@ -92,21 +75,7 @@ var AssignTask = common.Shortcut{
 
 		if removeStr := runtime.Str("remove"); removeStr != "" {
 			body := buildMembersBody(removeStr, "assignee", "")
-			apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
-				HttpMethod:  http.MethodPost,
-				ApiPath:     "/open-apis/task/v2/tasks/" + taskId + "/remove_members",
-				QueryParams: queryParams,
-				Body:        body,
-			})
-
-			var result map[string]interface{}
-			if err == nil {
-				if parseErr := json.Unmarshal(apiResp.RawBody, &result); parseErr != nil {
-					return WrapTaskError(ErrCodeTaskInternalError, fmt.Sprintf("failed to parse response: %v", parseErr), "parse remove members")
-				}
-			}
-
-			data, err := HandleTaskApiResult(result, err, "remove task members")
+			data, err := callTaskAPITyped(runtime, http.MethodPost, "/open-apis/task/v2/tasks/"+taskId+"/remove_members", params, body)
 			if err != nil {
 				return err
 			}

shortcuts/task/task_assign_test.go

@@ -4,14 +4,100 @@
 package task
 
 import (
+	"errors"
 	"testing"
 
 	"github.com/spf13/cobra"
 
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 	"github.com/smartystreets/goconvey/convey"
 )
 
+// TestAssignTask_RequiresAddOrRemove covers the Validate guard: neither --add
+// nor --remove yields a typed validation error (exit 2) before any API call.
+func TestAssignTask_RequiresAddOrRemove(t *testing.T) {
+	f, stdout, _, _ := taskShortcutTestFactory(t)
+
+	s := AssignTask
+	args := []string{"+assign", "--task-id", "task-1", "--as", "bot", "--format", "json"}
+	err := runMountedTaskShortcut(t, s, args, f, stdout)
+
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("err = %T, want *errs.ValidationError; err = %v", err, err)
+	}
+	if ve.Subtype != errs.SubtypeInvalidArgument {
+		t.Errorf("subtype = %q, want %q", ve.Subtype, errs.SubtypeInvalidArgument)
+	}
+	if got := output.ExitCodeOf(err); got != output.ExitValidation {
+		t.Errorf("exit code = %d, want %d", got, output.ExitValidation)
+	}
+}
+
+// TestAssignTask_MalformedResponse covers the Execute parse-response arm: a
+// 200 with an unparseable body surfaces a typed internal invalid_response
+// error (exit 5).
+func TestAssignTask_MalformedResponse(t *testing.T) {
+	f, stdout, _, reg := taskShortcutTestFactory(t)
+	warmTenantToken(t, f, reg)
+
+	reg.Register(&httpmock.Stub{
+		Method:  "POST",
+		URL:     "/open-apis/task/v2/tasks/task-1/add_members",
+		Status:  200,
+		RawBody: []byte("{not-json"),
+	})
+
+	s := AssignTask
+	args := []string{"+assign", "--task-id", "task-1", "--add", "ou_user_1", "--as", "bot", "--format", "json"}
+	err := runMountedTaskShortcut(t, s, args, f, stdout)
+
+	var ie *errs.InternalError
+	if !errors.As(err, &ie) {
+		t.Fatalf("err = %T, want *errs.InternalError; err = %v", err, err)
+	}
+	if ie.Subtype != errs.SubtypeInvalidResponse {
+		t.Errorf("subtype = %q, want %q", ie.Subtype, errs.SubtypeInvalidResponse)
+	}
+	if got := output.ExitCodeOf(err); got != output.ExitInternal {
+		t.Errorf("exit code = %d, want %d", got, output.ExitInternal)
+	}
+}
+
+// TestAssignTask_MalformedResponse_RemoveArm covers the Execute remove-members
+// parse arm: with only --remove set, the add arm is skipped and the
+// remove_members POST returns a 200 with an unparseable body, which must
+// surface a typed internal invalid_response error (exit 5).
+func TestAssignTask_MalformedResponse_RemoveArm(t *testing.T) {
+	f, stdout, _, reg := taskShortcutTestFactory(t)
+	warmTenantToken(t, f, reg)
+
+	reg.Register(&httpmock.Stub{
+		Method:  "POST",
+		URL:     "/open-apis/task/v2/tasks/task-1/remove_members",
+		Status:  200,
+		RawBody: []byte("{not-json"),
+	})
+
+	s := AssignTask
+	args := []string{"+assign", "--task-id", "task-1", "--remove", "ou_user_1", "--as", "bot", "--format", "json"}
+	err := runMountedTaskShortcut(t, s, args, f, stdout)
+
+	var ie *errs.InternalError
+	if !errors.As(err, &ie) {
+		t.Fatalf("err = %T, want *errs.InternalError; err = %v", err, err)
+	}
+	if ie.Subtype != errs.SubtypeInvalidResponse {
+		t.Errorf("subtype = %q, want %q", ie.Subtype, errs.SubtypeInvalidResponse)
+	}
+	if got := output.ExitCodeOf(err); got != output.ExitInternal {
+		t.Errorf("exit code = %d, want %d", got, output.ExitInternal)
+	}
+}
+
 func TestBuildMembersBody(t *testing.T) {
 	convey.Convey("Build with ids and token", t, func() {
 		body := buildMembersBody("u1, u2 , ", "assignee", "token1")