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

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

Add Markdown 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/sheets/|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/markdown/|shortcuts/minutes/|shortcuts/okr/|shortcuts/sheets/|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/sheets/|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/markdown/|shortcuts/minutes/|shortcuts/okr/|shortcuts/sheets/|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/sheets/|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/markdown/|shortcuts/minutes/|shortcuts/okr/|shortcuts/sheets/|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

@@ -25,6 +25,7 @@ var migratedCommonHelperPaths = []string{
 	"shortcuts/drive/",
 	"shortcuts/event/",
 	"shortcuts/mail/",
+	"shortcuts/markdown/",
 	"shortcuts/minutes/",
 	"shortcuts/okr/",
 	"shortcuts/sheets/",

lint/errscontract/rule_no_legacy_envelope_literal.go

@@ -26,6 +26,7 @@ var migratedEnvelopePaths = []string{
 	"shortcuts/drive/",
 	"shortcuts/event/",
 	"shortcuts/mail/",
+	"shortcuts/markdown/",
 	"shortcuts/minutes/",
 	"shortcuts/okr/",
 	"shortcuts/sheets/",

lint/errscontract/rules_test.go

@@ -620,6 +620,7 @@ func boom() error {
 
 func TestCheckNoLegacyEnvelopeLiteral_RejectsExitErrorLiteralOnMigratedShortcutPaths(t *testing.T) {
 	for _, path := range []string{
+		"shortcuts/markdown/markdown_fetch.go",
 		"shortcuts/okr/okr_image_upload.go",
 		"shortcuts/task/task_update.go",
 		"shortcuts/whiteboard/whiteboard_update.go",
@@ -953,6 +954,7 @@ func TestCheckNoLegacyCommonHelperCall_RejectsLegacyHelpersOnMigratedPath(t *tes
 		"shortcuts/doc/docs_fetch_v2.go",
 		"shortcuts/drive/drive_search.go",
 		"shortcuts/mail/mail_send.go",
+		"shortcuts/markdown/markdown_fetch.go",
 		"shortcuts/okr/okr_progress_create.go",
 		"shortcuts/sheets/helpers.go",
 		"shortcuts/task/task_update.go",
@@ -1039,6 +1041,23 @@ func boom() {
 	}
 }
 
+func TestCheckNoLegacyCommonHelperCall_CoversMarkdownPathWithAliasAndFunctionValue(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/markdown/markdown_fetch.go", src)
+	if len(v) != 2 {
+		t.Fatalf("expected 2 violations for aliased/function-value legacy helpers on markdown path, got %d: %+v", len(v), v)
+	}
+}
+
 func TestCheckNoLegacyCommonHelperCall_AllowsNonMigratedPath(t *testing.T) {
 	src := `package contact
 

shortcuts/common/runner.go

@@ -676,30 +676,10 @@ func WrapInputStatErrorTyped(err error, readMsg ...string) error {
 		WithCause(err)
 }
 
-// WrapSaveErrorByCategory maps a FileIO.Save error to structured output errors,
-// using standardized messages and the given error category (e.g. "api_error", "io").
-// Path validation errors always use ErrValidation (exit code 2).
-//
-// Deprecated: use WrapSaveErrorTyped for typed error envelopes.
-func WrapSaveErrorByCategory(err error, category string) error {
-	if err == nil {
-		return nil
-	}
-	var me *fileio.MkdirError
-	switch {
-	case errors.Is(err, fileio.ErrPathValidation):
-		return output.ErrValidation("unsafe output path: %s", err)
-	case errors.As(err, &me):
-		return output.Errorf(output.ExitInternal, category, "cannot create parent directory: %s", err)
-	default:
-		return output.Errorf(output.ExitInternal, category, "cannot create file: %s", err)
-	}
-}
-
 // WrapSaveErrorTyped maps a FileIO.Save error to typed validation/internal errors.
-// Unlike WrapSaveErrorByCategory, non-path failures always emit the canonical
-// "internal" wire type: call sites migrating from a custom category
-// (e.g. "io", "api_error") change their envelope's type field.
+// Non-path failures always emit the canonical "internal" wire type; call sites
+// migrating from a custom category (e.g. "io", "api_error") change their
+// envelope's type field.
 func WrapSaveErrorTyped(err error) error {
 	if err == nil {
 		return nil

shortcuts/markdown/helpers.go

@@ -6,7 +6,6 @@ package markdown
 import (
 	"bytes"
 	"context"
-	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -19,7 +18,6 @@ import (
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/client"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -85,16 +83,18 @@ func (spec markdownUploadSpec) Target() markdownUploadTarget {
 func validateMarkdownSpec(runtime *common.RuntimeContext, spec markdownUploadSpec, requireName bool) error {
 	switch {
 	case spec.ContentSet && spec.FileSet:
-		return common.FlagErrorf("--content and --file are mutually exclusive")
+		return markdownValidationError("--content and --file are mutually exclusive").
+			WithParams(markdownInvalidParam("--content", "mutually exclusive"), markdownInvalidParam("--file", "mutually exclusive"))
 	case !spec.ContentSet && !spec.FileSet:
-		return common.FlagErrorf("specify exactly one of --content or --file")
+		return markdownValidationError("specify exactly one of --content or --file").
+			WithParams(markdownInvalidParam("--content", "required; specify exactly one"), markdownInvalidParam("--file", "required; specify exactly one"))
 	}
 
 	if markdownFlagExplicitlyEmpty(runtime, "folder-token") {
-		return common.FlagErrorf("--folder-token cannot be empty; omit it to upload into Drive root folder")
+		return markdownValidationParamError("--folder-token", "--folder-token cannot be empty; omit it to upload into Drive root folder")
 	}
 	if markdownFlagExplicitlyEmpty(runtime, "wiki-token") {
-		return common.FlagErrorf("--wiki-token cannot be empty; provide a valid wiki node token or omit the flag entirely")
+		return markdownValidationParamError("--wiki-token", "--wiki-token cannot be empty; provide a valid wiki node token or omit the flag entirely")
 	}
 	targets := 0
 	if spec.FolderToken != "" {
@@ -104,22 +104,23 @@ func validateMarkdownSpec(runtime *common.RuntimeContext, spec markdownUploadSpe
 		targets++
 	}
 	if targets > 1 {
-		return common.FlagErrorf("--folder-token and --wiki-token are mutually exclusive")
+		return markdownValidationError("--folder-token and --wiki-token are mutually exclusive").
+			WithParams(markdownInvalidParam("--folder-token", "mutually exclusive"), markdownInvalidParam("--wiki-token", "mutually exclusive"))
 	}
 	if spec.FolderToken != "" {
 		if err := validate.ResourceName(spec.FolderToken, "--folder-token"); err != nil {
-			return output.ErrValidation("%s", err)
+			return markdownValidationParamError("--folder-token", "%s", err).WithCause(err)
 		}
 	}
 	if spec.WikiToken != "" {
 		if err := validate.ResourceName(spec.WikiToken, "--wiki-token"); err != nil {
-			return output.ErrValidation("%s", err)
+			return markdownValidationParamError("--wiki-token", "%s", err).WithCause(err)
 		}
 	}
 
 	if requireName && spec.ContentSet {
 		if strings.TrimSpace(spec.FileName) == "" {
-			return common.FlagErrorf("--name is required when using --content")
+			return markdownValidationParamError("--name", "--name is required when using --content")
 		}
 		if err := validateMarkdownFileName(spec.FileName, "--name"); err != nil {
 			return err
@@ -128,10 +129,10 @@ func validateMarkdownSpec(runtime *common.RuntimeContext, spec markdownUploadSpe
 
 	if spec.FileSet {
 		if strings.TrimSpace(spec.FilePath) == "" {
-			return common.FlagErrorf("--file cannot be empty")
+			return markdownValidationParamError("--file", "--file cannot be empty")
 		}
 		if _, err := validate.SafeInputPath(spec.FilePath); err != nil {
-			return output.ErrValidation("unsafe file path: %s", err)
+			return markdownValidationParamError("--file", "unsafe file path: %s", err).WithCause(err)
 		}
 		if err := validateMarkdownFileName(filepath.Base(spec.FilePath), "--file"); err != nil {
 			return err
@@ -154,10 +155,10 @@ func markdownFlagExplicitlyEmpty(runtime *common.RuntimeContext, flagName string
 func validateMarkdownFileName(name, flagName string) error {
 	trimmed := strings.TrimSpace(name)
 	if trimmed == "" {
-		return common.FlagErrorf("%s cannot be empty", flagName)
+		return markdownValidationParamError(flagName, "%s cannot be empty", flagName)
 	}
 	if !strings.HasSuffix(strings.ToLower(trimmed), ".md") {
-		return common.FlagErrorf("%s must end with .md", flagName)
+		return markdownValidationParamError(flagName, "%s must end with .md", flagName)
 	}
 	return nil
 }
@@ -201,22 +202,9 @@ func openMarkdownDownload(ctx context.Context, runtime *common.RuntimeContext, f
 	return resp, nil
 }
 
-func wrapMarkdownDownloadError(err error) error {
-	// Preserve any already-classified error: legacy *output.ExitError or any
-	// typed errs.* error. Only un-classified errors get wrapped as network.
-	var exitErr *output.ExitError
-	if errors.As(err, &exitErr) {
-		return err
-	}
-	if _, ok := errs.ProblemOf(err); ok {
-		return err
-	}
-	return output.ErrNetwork("download failed: %s", err)
-}
-
 func validateNonEmptyMarkdownSize(size int64) error {
 	if size == 0 {
-		return output.ErrValidation("%s", markdownEmptyContentError)
+		return markdownValidationError("%s", markdownEmptyContentError)
 	}
 	return nil
 }
@@ -227,12 +215,12 @@ func markdownSourceSize(runtime *common.RuntimeContext, spec markdownUploadSpec)
 		size = int64(len(spec.Content))
 	} else {
 		if strings.TrimSpace(spec.FilePath) == "" {
-			return 0, common.FlagErrorf("--file cannot be empty")
+			return 0, markdownValidationParamError("--file", "--file cannot be empty")
 		}
 
 		info, err := runtime.FileIO().Stat(spec.FilePath)
 		if err != nil {
-			return 0, common.WrapInputStatError(err)
+			return 0, withMarkdownFileParam(common.WrapInputStatErrorTyped(err), "--file")
 		}
 		size = info.Size()
 	}
@@ -424,7 +412,7 @@ func uploadMarkdownFileAll(runtime *common.RuntimeContext, spec markdownUploadSp
 	return withMarkdownUploadRetryResult(runtime, markdownUploadAllAction, func() (markdownUploadResult, error) {
 		fileReader, err := openReader()
 		if err != nil {
-			return markdownUploadResult{}, common.WrapInputStatErrorTyped(err)
+			return markdownUploadResult{}, withMarkdownFileParam(common.WrapInputStatErrorTyped(err), "--file")
 		}
 		defer fileReader.Close()
 
@@ -491,7 +479,7 @@ func uploadMarkdownFileMultipart(runtime *common.RuntimeContext, spec markdownUp
 
 	fileReader, err := openReader()
 	if err != nil {
-		return markdownUploadResult{}, common.WrapInputStatErrorTyped(err)
+		return markdownUploadResult{}, withMarkdownFileParam(common.WrapInputStatErrorTyped(err), "--file")
 	}
 	defer fileReader.Close()
 
@@ -563,7 +551,7 @@ func uploadMarkdownMultipartParts(runtime *common.RuntimeContext, fileReader io.
 
 		n, readErr := io.ReadFull(fileReader, buffer[:int(chunkSize)])
 		if readErr != nil {
-			return output.ErrValidation("cannot read file: %s", readErr)
+			return markdownValidationParamError("--file", "cannot read file: %s", readErr).WithCause(readErr)
 		}
 
 		fd := larkcore.NewFormdata()

shortcuts/markdown/markdown_diff.go

@@ -5,7 +5,6 @@ package markdown
 
 import (
 	"context"
-	"errors"
 	"fmt"
 	"io"
 	"regexp"
@@ -14,6 +13,7 @@ import (
 
 	"github.com/sergi/go-diff/diffmatchpatch"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -65,7 +65,7 @@ type markdownDiffHunkRange struct {
 
 func validateMarkdownDiffSpec(runtime *common.RuntimeContext, spec markdownDiffSpec) error {
 	if err := validate.ResourceName(spec.FileToken, "--file-token"); err != nil {
-		return output.ErrValidation("%s", err)
+		return markdownValidationParamError("--file-token", "%s", err).WithCause(err)
 	}
 	if spec.FromVersion != "" {
 		if err := validateMarkdownDiffVersionValue(spec.FromVersion, "--from-version"); err != nil {
@@ -79,40 +79,45 @@ func validateMarkdownDiffSpec(runtime *common.RuntimeContext, spec markdownDiffS
 	}
 	if spec.FilePath != "" {
 		if _, err := validate.SafeInputPath(spec.FilePath); err != nil {
-			return output.ErrValidation("unsafe file path: %s", err)
+			return markdownValidationParamError("--file", "unsafe file path: %s", err).WithCause(err)
 		}
 		if err := validateMarkdownFileName(spec.FilePath, "--file"); err != nil {
 			return err
 		}
 	}
 	if spec.ContextLines < 0 {
-		return output.ErrValidation("--context-lines must be >= 0")
+		return markdownValidationParamError("--context-lines", "--context-lines must be >= 0")
 	}
 	if spec.Format != "" && spec.Format != "json" && spec.Format != "pretty" {
-		return output.ErrValidation("markdown +diff only supports --format json or pretty")
+		return markdownValidationParamError("--format", "markdown +diff only supports --format json or pretty")
 	}
 	if spec.FilePath == "" {
 		if spec.FromVersion == "" && spec.ToVersion == "" {
-			return common.FlagErrorf("specify --from-version, or both --from-version and --to-version, or use --file for remote vs local diff")
+			return markdownValidationError("specify --from-version, or both --from-version and --to-version, or use --file for remote vs local diff").
+				WithParams(
+					markdownInvalidParam("--from-version", "required; specify one"),
+					markdownInvalidParam("--to-version", "required; specify one"),
+					markdownInvalidParam("--file", "required; specify one"),
+				)
 		}
 		if spec.FromVersion == "" && spec.ToVersion != "" {
-			return common.FlagErrorf("--to-version requires --from-version")
+			return markdownValidationParamError("--to-version", "--to-version requires --from-version")
 		}
 		return nil
 	}
 	if spec.ToVersion != "" {
-		return common.FlagErrorf("--to-version is not supported together with --file")
+		return markdownValidationParamError("--to-version", "--to-version is not supported together with --file")
 	}
 	return nil
 }
 
 func validateMarkdownDiffVersionValue(value, flagName string) error {
 	value = strings.TrimSpace(value)
 	if value == "" {
-		return output.ErrValidation("%s cannot be empty", flagName)
+		return markdownValidationParamError(flagName, "%s cannot be empty", flagName)
 	}
 	if !markdownDiffVersionRe.MatchString(value) {
-		return output.ErrValidation("%s must be a numeric version string", flagName)
+		return markdownValidationParamError(flagName, "%s must be a numeric version string", flagName)
 	}
 	return nil
 }
@@ -178,17 +183,16 @@ func downloadMarkdownContent(ctx context.Context, runtime *common.RuntimeContext
 func readMarkdownLocalFile(runtime *common.RuntimeContext, filePath string) (string, error) {
 	f, err := runtime.FileIO().Open(filePath)
 	if err != nil {
-		return "", common.WrapInputStatError(err)
+		return "", withMarkdownFileParam(common.WrapInputStatErrorTyped(err), "--file")
 	}
 	defer f.Close()
 
 	payload, err := readMarkdownDiffPayload(f, "local Markdown file")
 	if err != nil {
-		var exitErr *output.ExitError
-		if errors.As(err, &exitErr) {
-			return "", err
+		if _, ok := errs.ProblemOf(err); ok {
+			return "", withMarkdownFileParam(err, "--file")
 		}
-		return "", output.ErrValidation("cannot read file: %s", err)
+		return "", markdownValidationParamError("--file", "cannot read file: %s", err).WithCause(err)
 	}
 	return string(payload), nil
 }
@@ -199,7 +203,7 @@ func readMarkdownDiffPayload(r io.Reader, source string) ([]byte, error) {
 		return nil, err
 	}
 	if len(payload) > markdownDiffMaxContentBytes {
-		return nil, output.ErrValidation("%s exceeds %s markdown +diff content limit", source, common.FormatSize(markdownDiffMaxContentBytes))
+		return nil, markdownValidationError("%s exceeds %s markdown +diff content limit", source, common.FormatSize(markdownDiffMaxContentBytes))
 	}
 	return payload, nil
 }