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

Emit structured validation, API, network, file, and internal error envelopes for Slides shortcuts so users and agents can recover from failed presentation workflows using stable type, subtype, param, and code fields.

Add Slides domain errscontract and golangci guards to prevent legacy envelope and common helper regressions.

Author: evandance

.golangci.yml

@@ -73,20 +73,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/base/|shortcuts/calendar/|shortcuts/contact/|shortcuts/doc/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/minutes/|shortcuts/okr/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|internal/event/consume/|cmd/event/|events/|shortcuts/event/)
+      - 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/base/|shortcuts/calendar/|shortcuts/contact/|shortcuts/doc/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/minutes/|shortcuts/okr/|shortcuts/slides/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|internal/event/consume/|cmd/event/|events/|shortcuts/event/)
         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/base/|shortcuts/calendar/|shortcuts/contact/|shortcuts/doc/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/minutes/|shortcuts/okr/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|shortcuts/common/mcp_client\.go|cmd/event/|events/|shortcuts/event/)
+      - path-except: (shortcuts/base/|shortcuts/calendar/|shortcuts/contact/|shortcuts/doc/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/minutes/|shortcuts/okr/|shortcuts/slides/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|shortcuts/common/mcp_client\.go|cmd/event/|events/|shortcuts/event/)
         text: errs-no-bare-wrap
         linters:
           - forbidigo
       # errs-no-legacy-helper enforced on domains whose shared validation/save
       # helpers have migrated to typed final errors.
-      - path-except: (shortcuts/base/|shortcuts/calendar/|shortcuts/contact/|shortcuts/doc/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/minutes/|shortcuts/okr/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|cmd/event/|events/|shortcuts/event/)
+      - path-except: (shortcuts/base/|shortcuts/calendar/|shortcuts/contact/|shortcuts/doc/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/minutes/|shortcuts/okr/|shortcuts/slides/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|cmd/event/|events/|shortcuts/event/)
         text: errs-no-legacy-helper
         linters:
           - forbidigo

lint/errscontract/rule_no_legacy_common_helper_call.go

@@ -27,6 +27,7 @@ var migratedCommonHelperPaths = []string{
 	"shortcuts/mail/",
 	"shortcuts/minutes/",
 	"shortcuts/okr/",
+	"shortcuts/slides/",
 	"shortcuts/task/",
 	"shortcuts/vc/",
 	"shortcuts/whiteboard/",

lint/errscontract/rule_no_legacy_envelope_literal.go

@@ -28,6 +28,7 @@ var migratedEnvelopePaths = []string{
 	"shortcuts/mail/",
 	"shortcuts/minutes/",
 	"shortcuts/okr/",
+	"shortcuts/slides/",
 	"shortcuts/task/",
 	"shortcuts/vc/",
 	"shortcuts/whiteboard/",

lint/errscontract/rules_test.go

@@ -954,6 +954,7 @@ func TestCheckNoLegacyCommonHelperCall_RejectsLegacyHelpersOnMigratedPath(t *tes
 		"shortcuts/drive/drive_search.go",
 		"shortcuts/mail/mail_send.go",
 		"shortcuts/okr/okr_progress_create.go",
+		"shortcuts/slides/slides_create.go",
 		"shortcuts/task/task_update.go",
 		"shortcuts/whiteboard/whiteboard_query.go",
 	}
@@ -1021,6 +1022,23 @@ func boom() {
 	}
 }
 
+func TestCheckNoLegacyCommonHelperCall_CoversSlidesPathWithAliasAndFunctionValue(t *testing.T) {
+	src := `package migrated
+
+import c "github.com/larksuite/cli/shortcuts/common"
+
+func boom() {
+	f := c.FlagErrorf
+	_ = f
+	c.WrapInputStatError(nil)
+}
+`
+	v := CheckNoLegacyCommonHelperCall("shortcuts/slides/slides_create.go", src)
+	if len(v) != 2 {
+		t.Fatalf("expected 2 violations for aliased/function-value legacy helpers on slides path, got %d: %+v", len(v), v)
+	}
+}
+
 func TestCheckNoLegacyCommonHelperCall_AllowsNonMigratedPath(t *testing.T) {
 	src := `package contact
 

shortcuts/slides/helpers.go

@@ -9,7 +9,7 @@ import (
 	"regexp"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -30,29 +30,29 @@ type presentationRef struct {
 func parsePresentationRef(input string) (presentationRef, error) {
 	raw := strings.TrimSpace(input)
 	if raw == "" {
-		return presentationRef{}, output.ErrValidation("--presentation cannot be empty")
+		return presentationRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--presentation cannot be empty").WithParam("--presentation")
 	}
 	// URL inputs: parse properly and only honor /slides/ or /wiki/ when they
 	// appear as a prefix of the URL path. Substring matching previously let
 	// e.g. `https://x/docx/foo?next=/slides/abc` resolve to token "abc".
 	if strings.Contains(raw, "://") {
 		u, err := url.Parse(raw)
 		if err != nil || u.Path == "" {
-			return presentationRef{}, output.ErrValidation("unsupported --presentation input %q: use an xml_presentation_id, a /slides/ URL, or a /wiki/ URL", raw)
+			return presentationRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported --presentation input %q: use an xml_presentation_id, a /slides/ URL, or a /wiki/ URL", raw).WithParam("--presentation")
 		}
 		if token, ok := tokenAfterPathPrefix(u.Path, "/slides/"); ok {
 			return presentationRef{Kind: "slides", Token: token}, nil
 		}
 		if token, ok := tokenAfterPathPrefix(u.Path, "/wiki/"); ok {
 			return presentationRef{Kind: "wiki", Token: token}, nil
 		}
-		return presentationRef{}, output.ErrValidation("unsupported --presentation input %q: use an xml_presentation_id, a /slides/ URL, or a /wiki/ URL", raw)
+		return presentationRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported --presentation input %q: use an xml_presentation_id, a /slides/ URL, or a /wiki/ URL", raw).WithParam("--presentation")
 	}
 	// Non-URL input must be a bare token — anything with path/query/fragment
 	// chars is rejected so partial-path inputs like `tmp/wiki/wikcn123` don't
 	// get silently accepted.
 	if strings.ContainsAny(raw, "/?#") {
-		return presentationRef{}, output.ErrValidation("unsupported --presentation input %q: use an xml_presentation_id, a /slides/ URL, or a /wiki/ URL", raw)
+		return presentationRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported --presentation input %q: use an xml_presentation_id, a /slides/ URL, or a /wiki/ URL", raw).WithParam("--presentation")
 	}
 	return presentationRef{Kind: "slides", Token: raw}, nil
 }
@@ -82,7 +82,7 @@ func resolvePresentationID(runtime *common.RuntimeContext, ref presentationRef)
 	case "slides":
 		return ref.Token, nil
 	case "wiki":
-		data, err := runtime.CallAPI(
+		data, err := runtime.CallAPITyped(
 			"GET",
 			"/open-apis/wiki/v2/spaces/get_node",
 			map[string]interface{}{"token": ref.Token},
@@ -95,14 +95,14 @@ func resolvePresentationID(runtime *common.RuntimeContext, ref presentationRef)
 		objType := common.GetString(node, "obj_type")
 		objToken := common.GetString(node, "obj_token")
 		if objType == "" || objToken == "" {
-			return "", output.Errorf(output.ExitAPI, "api_error", "wiki get_node returned incomplete node data")
+			return "", errs.NewInternalError(errs.SubtypeInvalidResponse, "wiki get_node returned incomplete node data")
 		}
 		if objType != "slides" {
-			return "", output.ErrValidation("wiki resolved to %q, but slides shortcuts require a slides presentation", objType)
+			return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "wiki resolved to %q, but slides shortcuts require a slides presentation", objType).WithParam("--presentation")
 		}
 		return objToken, nil
 	default:
-		return "", output.ErrValidation("unsupported presentation ref kind %q", ref.Kind)
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported presentation ref kind %q", ref.Kind)
 	}
 }
 
@@ -191,7 +191,7 @@ var xmlIdAttrRegex = regexp.MustCompile(`(?s)(?:^|\s)id\s*=\s*(["'])(.*?)(["'])`
 func ensureXMLRootID(xmlFragment, want string) (string, error) {
 	m := xmlRootOpenTagRegex.FindStringSubmatchIndex(xmlFragment)
 	if m == nil {
-		return "", fmt.Errorf("no root element found in XML fragment")
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "no root element found in XML fragment")
 	}
 	prefix := xmlFragment[m[2]:m[3]]
 	tagName := xmlFragment[m[4]:m[5]]

shortcuts/slides/slides_create.go

@@ -10,7 +10,7 @@ import (
 	"path/filepath"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -45,24 +45,24 @@ var SlidesCreate = common.Shortcut{
 		if slidesStr := runtime.Str("slides"); slidesStr != "" {
 			var slides []string
 			if err := json.Unmarshal([]byte(slidesStr), &slides); err != nil {
-				return common.FlagErrorf("--slides invalid JSON, must be an array of XML strings")
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--slides invalid JSON, must be an array of XML strings").WithParam("--slides")
 			}
 			if len(slides) > maxSlidesPerCreate {
-				return common.FlagErrorf("--slides array exceeds maximum of %d slides; create the presentation first, then add slides via xml_presentation.slide.create", maxSlidesPerCreate)
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--slides array exceeds maximum of %d slides; create the presentation first, then add slides via xml_presentation.slide.create", maxSlidesPerCreate).WithParam("--slides")
 			}
 			// Validate placeholder paths up front so we don't create a presentation
 			// only to fail mid-way on a missing local file.
 			for _, path := range extractImagePlaceholderPaths(slides) {
 				stat, err := runtime.FileIO().Stat(path)
 				if err != nil {
-					return common.WrapInputStatError(err, fmt.Sprintf("--slides @%s: file not found", path))
+					return slidesInputStatError(err, "--slides", fmt.Sprintf("--slides @%s: file not found", path))
 				}
 				if !stat.Mode().IsRegular() {
-					return common.FlagErrorf("--slides @%s: must be a regular file", path)
+					return errs.NewValidationError(errs.SubtypeInvalidArgument, "--slides @%s: must be a regular file", path).WithParam("--slides")
 				}
 				if stat.Size() > common.MaxDriveMediaUploadSinglePartSize {
-					return common.FlagErrorf("--slides @%s: file size %s exceeds 20 MB limit for slides image upload",
-						path, common.FormatSize(stat.Size()))
+					return errs.NewValidationError(errs.SubtypeInvalidArgument, "--slides @%s: file size %s exceeds 20 MB limit for slides image upload",
+						path, common.FormatSize(stat.Size())).WithParam("--slides")
 				}
 			}
 		}
@@ -128,7 +128,7 @@ var SlidesCreate = common.Shortcut{
 		slidesStr := runtime.Str("slides")
 
 		// Step 1: Create presentation
-		data, err := runtime.CallAPI(
+		data, err := runtime.CallAPITyped(
 			"POST",
 			"/open-apis/slides_ai/v1/xml_presentations",
 			nil,
@@ -144,7 +144,7 @@ var SlidesCreate = common.Shortcut{
 
 		presentationID := common.GetString(data, "xml_presentation_id")
 		if presentationID == "" {
-			return output.Errorf(output.ExitAPI, "api_error", "slides create returned no xml_presentation_id")
+			return errs.NewInternalError(errs.SubtypeInvalidResponse, "slides create returned no xml_presentation_id")
 		}
 
 		result := map[string]interface{}{
@@ -168,9 +168,7 @@ var SlidesCreate = common.Shortcut{
 				if len(placeholders) > 0 {
 					tokens, uploaded, err := uploadSlidesPlaceholders(runtime, presentationID, placeholders)
 					if err != nil {
-						return output.Errorf(output.ExitAPI, "api_error",
-							"image upload failed: %v (presentation %s was created; %d image(s) uploaded before failure)",
-							err, presentationID, uploaded)
+						return appendSlidesProgressHint(err, fmt.Sprintf("presentation %s was created; %d image(s) uploaded before failure", presentationID, uploaded))
 					}
 					for i := range slides {
 						slides[i] = replaceImagePlaceholders(slides[i], tokens)
@@ -185,7 +183,7 @@ var SlidesCreate = common.Shortcut{
 
 				var slideIDs []string
 				for i, slideXML := range slides {
-					slideData, err := runtime.CallAPI(
+					slideData, err := runtime.CallAPITyped(
 						"POST",
 						slideURL,
 						map[string]interface{}{"revision_id": -1},
@@ -194,9 +192,7 @@ var SlidesCreate = common.Shortcut{
 						},
 					)
 					if err != nil {
-						return output.Errorf(output.ExitAPI, "api_error",
-							"slide %d/%d failed: %v (presentation %s was created; %d slide(s) added before failure)",
-							i+1, len(slides), err, presentationID, i)
+						return appendSlidesProgressHint(err, fmt.Sprintf("adding slide %d/%d failed; presentation %s was created, %d slide(s) added before failure", i+1, len(slides), presentationID, i))
 					}
 					if sid := common.GetString(slideData, "slide_id"); sid != "" {
 						slideIDs = append(slideIDs, sid)
@@ -256,18 +252,18 @@ func uploadSlidesPlaceholders(runtime *common.RuntimeContext, presentationID str
 	for i, path := range paths {
 		stat, err := runtime.FileIO().Stat(path)
 		if err != nil {
-			return tokens, i, common.WrapInputStatError(err, fmt.Sprintf("@%s: file not found", path))
+			return tokens, i, slidesInputStatError(err, "--slides", fmt.Sprintf("@%s: file not found", path))
 		}
 		if !stat.Mode().IsRegular() {
-			return tokens, i, output.ErrValidation("@%s: must be a regular file", path)
+			return tokens, i, errs.NewValidationError(errs.SubtypeInvalidArgument, "@%s: must be a regular file", path).WithParam("--slides")
 		}
 		fileName := filepath.Base(path)
 		fmt.Fprintf(runtime.IO().ErrOut, "Uploading image %d/%d: %s (%s)\n",
 			i+1, len(paths), fileName, common.FormatSize(stat.Size()))
 
 		token, err := uploadSlidesMedia(runtime, path, fileName, stat.Size(), presentationID)
 		if err != nil {
-			return tokens, i, fmt.Errorf("@%s: %w", path, err)
+			return tokens, i, fmt.Errorf("@%s: %w", path, err) //nolint:forbidigo // intermediate; preserves typed cause via %w, reclassified by appendSlidesProgressHint at the call site
 		}
 		tokens[path] = token
 	}

shortcuts/slides/slides_create_test.go

@@ -6,12 +6,14 @@ package slides
 import (
 	"bytes"
 	"encoding/json"
+	"errors"
 	"os"
 	"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"
@@ -400,15 +402,21 @@ func TestSlidesCreateWithSlidesPartialFailure(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected error for partial failure, got nil")
 	}
-	errMsg := err.Error()
-	if !strings.Contains(errMsg, "pres_partial") {
-		t.Fatalf("error should contain presentation ID, got: %s", errMsg)
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected a typed errs.* error, got %v", err)
 	}
-	if !strings.Contains(errMsg, "slide 2/2") {
-		t.Fatalf("error should indicate slide 2/2 failed, got: %s", errMsg)
+	// The presentation was created but a slide add failed; the recovery hint
+	// carries the partial-progress context (which presentation exists, how many
+	// slides landed) so the caller can resume without recreating.
+	if !strings.Contains(p.Hint, "pres_partial") {
+		t.Fatalf("hint should contain presentation ID, got: %s", p.Hint)
 	}
-	if !strings.Contains(errMsg, "1 slide(s) added") {
-		t.Fatalf("error should report 1 slide added before failure, got: %s", errMsg)
+	if !strings.Contains(p.Hint, "slide 2/2") {
+		t.Fatalf("hint should indicate slide 2/2 failed, got: %s", p.Hint)
+	}
+	if !strings.Contains(p.Hint, "1 slide(s) added") {
+		t.Fatalf("hint should report 1 slide added before failure, got: %s", p.Hint)
 	}
 }
 
@@ -457,6 +465,71 @@ func TestSlidesCreateWithSlidesExceedsMax(t *testing.T) {
 	}
 }
 
+// TestSlidesCreateValidationParam locks Param=="--slides" on the pure
+// validation rejections, so callers route on the typed field rather than the
+// message.
+func TestSlidesCreateValidationParam(t *testing.T) {
+	t.Parallel()
+
+	elems := make([]string, 11)
+	for i := range elems {
+		elems[i] = `"<slide/>"`
+	}
+	exceedsMax := "[" + strings.Join(elems, ",") + "]"
+
+	tests := []struct {
+		name   string
+		slides string
+	}{
+		{"invalid JSON", "not json"},
+		{"exceeds max", exceedsMax},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+			err := runSlidesCreateShortcut(t, f, stdout, []string{
+				"+create",
+				"--slides", tt.slides,
+				"--as", "user",
+			})
+
+			var ve *errs.ValidationError
+			if !errors.As(err, &ve) {
+				t.Fatalf("err = %v, want *errs.ValidationError", err)
+			}
+			if ve.Param != "--slides" {
+				t.Fatalf("Param = %q, want --slides", ve.Param)
+			}
+		})
+	}
+}
+
+// TestSlidesCreatePlaceholderMissingParam guards the create.go caller wiring:
+// a missing @-placeholder file must surface a --slides-tagged validation error
+// through the shared slidesInputStatError helper.
+func TestSlidesCreatePlaceholderMissingParam(t *testing.T) {
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	slidesJSON := `["<slide><data><img src=\"@./missing.png\"/></data></slide>"]`
+	err := runSlidesCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--slides", slidesJSON,
+		"--as", "user",
+	})
+
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("err = %v, want *errs.ValidationError", err)
+	}
+	if ve.Param != "--slides" {
+		t.Fatalf("Param = %q, want --slides", ve.Param)
+	}
+}
+
 // TestSlidesCreateWithSlidesEmptyArray verifies that --slides '[]' behaves like no --slides.
 func TestSlidesCreateWithSlidesEmptyArray(t *testing.T) {
 	t.Parallel()