feat(slides): add image upload via +media-upload and @path placeholders in +create (#450)

- New `slides +media-upload` shortcut: upload a local image to a slides
  presentation and return the file_token for use in <img src="...">.
- `slides +create --slides` now supports `@./path.png` placeholders that
  are auto-uploaded and replaced with file_tokens.
- Reject images >20 MB (multipart upload not supported for slide_file).
- Support wiki URL resolution for --presentation flag.

Author: ViperCai

shortcuts/slides/helpers.go

@@ -0,0 +1,177 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"fmt"
+	"net/url"
+	"regexp"
+	"strings"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// presentationRef holds a parsed --presentation input.
+//
+// Slides shortcuts accept three input shapes:
+//   - a raw xml_presentation_id token
+//   - a slides URL like https://<host>/slides/<token>
+//   - a wiki URL like https://<host>/wiki/<token> (must resolve to obj_type=slides)
+type presentationRef struct {
+	Kind  string // "slides" | "wiki"
+	Token string
+}
+
+// parsePresentationRef extracts a presentation token from a token, slides URL, or wiki URL.
+// Wiki tokens are returned unresolved; callers must run resolveWikiToSlidesToken to
+// obtain the real xml_presentation_id and verify obj_type=slides.
+func parsePresentationRef(input string) (presentationRef, error) {
+	raw := strings.TrimSpace(input)
+	if raw == "" {
+		return presentationRef{}, output.ErrValidation("--presentation cannot be empty")
+	}
+	// 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)
+		}
+		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)
+	}
+	// 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{Kind: "slides", Token: raw}, nil
+}
+
+// tokenAfterPathPrefix extracts the first path segment after prefix from path.
+// Returns ("", false) if path doesn't start with prefix or the segment is empty.
+func tokenAfterPathPrefix(path, prefix string) (string, bool) {
+	if !strings.HasPrefix(path, prefix) {
+		return "", false
+	}
+	rest := path[len(prefix):]
+	if i := strings.IndexByte(rest, '/'); i >= 0 {
+		rest = rest[:i]
+	}
+	rest = strings.TrimSpace(rest)
+	if rest == "" {
+		return "", false
+	}
+	return rest, true
+}
+
+// resolvePresentationID resolves a parsed ref into an xml_presentation_id.
+// Slides refs pass through; wiki refs are looked up via wiki.spaces.get_node and
+// must resolve to obj_type=slides.
+func resolvePresentationID(runtime *common.RuntimeContext, ref presentationRef) (string, error) {
+	switch ref.Kind {
+	case "slides":
+		return ref.Token, nil
+	case "wiki":
+		data, err := runtime.CallAPI(
+			"GET",
+			"/open-apis/wiki/v2/spaces/get_node",
+			map[string]interface{}{"token": ref.Token},
+			nil,
+		)
+		if err != nil {
+			return "", err
+		}
+		node := common.GetMap(data, "node")
+		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")
+		}
+		if objType != "slides" {
+			return "", output.ErrValidation("wiki resolved to %q, but slides shortcuts require a slides presentation", objType)
+		}
+		return objToken, nil
+	default:
+		return "", output.ErrValidation("unsupported presentation ref kind %q", ref.Kind)
+	}
+}
+
+// imgSrcPlaceholderRegex matches `src="@<path>"` or `src='@<path>'` inside <img> tags.
+// The "@" prefix is the magic marker for "this is a local file path; upload it and
+// replace with file_token".
+//
+// Match groups:
+//
+//	1: opening quote character (so we can replace symmetrically)
+//	2: the path string (everything inside the quotes after the leading @)
+//
+// We deliberately scope to <img ... src="@..."> rather than any src= so other
+// schema elements (like icon/iconType) aren't accidentally rewritten.
+// `\s*=\s*` tolerates `src = "..."` style attributes (XML allows whitespace
+// around `=`); without it we'd silently leave such placeholders unrewritten.
+var imgSrcPlaceholderRegex = regexp.MustCompile(`(?s)<img\b[^>]*?\bsrc\s*=\s*(["'])@([^"']+)(["'])`)
+
+// extractImagePlaceholderPaths returns the de-duplicated list of local paths
+// referenced via <img src="@path"> in the given slide XML strings.
+//
+// Order is preserved (first occurrence wins) so dry-run / progress messages are
+// stable across runs.
+func extractImagePlaceholderPaths(slideXMLs []string) []string {
+	var paths []string
+	seen := map[string]bool{}
+	for _, xml := range slideXMLs {
+		matches := imgSrcPlaceholderRegex.FindAllStringSubmatch(xml, -1)
+		for _, m := range matches {
+			if m[1] != m[3] {
+				// Mismatched opening/closing quotes — Go's RE2 has no backreferences,
+				// so we filter it here. Treat as malformed XML and skip.
+				continue
+			}
+			path := strings.TrimSpace(m[2])
+			if path == "" || seen[path] {
+				continue
+			}
+			seen[path] = true
+			paths = append(paths, path)
+		}
+	}
+	return paths
+}
+
+// replaceImagePlaceholders rewrites <img src="@path"> occurrences in the input
+// XML by looking up each path in tokens. Paths missing from the map are left
+// untouched (callers should ensure the map is complete).
+func replaceImagePlaceholders(slideXML string, tokens map[string]string) string {
+	return imgSrcPlaceholderRegex.ReplaceAllStringFunc(slideXML, func(match string) string {
+		sub := imgSrcPlaceholderRegex.FindStringSubmatch(match)
+		if len(sub) < 4 {
+			return match
+		}
+		quote, path, closeQuote := sub[1], sub[2], sub[3]
+		if quote != closeQuote {
+			// Mismatched quotes — see extractImagePlaceholderPaths.
+			return match
+		}
+		token, ok := tokens[strings.TrimSpace(path)]
+		if !ok {
+			return match
+		}
+		// Replace only the `"@<path>"` segment (quotes inclusive) so any
+		// surrounding attrs and whitespace around `=` stay intact. Looking up
+		// by the literal `@<path>"` (with closing quote) avoids accidentally
+		// matching the same path elsewhere in the tag.
+		oldQuoted := fmt.Sprintf("%s@%s%s", quote, path, closeQuote)
+		newQuoted := fmt.Sprintf("%s%s%s", quote, token, closeQuote)
+		return strings.Replace(match, oldQuoted, newQuoted, 1)
+	})
+}

shortcuts/slides/helpers_test.go

@@ -0,0 +1,191 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func TestParsePresentationRef(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name      string
+		input     string
+		wantKind  string
+		wantToken string
+		wantErr   string
+	}{
+		{name: "raw token", input: "slidesXXXXXXXXXXXXXXXXXXXXXX", wantKind: "slides", wantToken: "slidesXXXXXXXXXXXXXXXXXXXXXX"},
+		{name: "slides URL", input: "https://x.feishu.cn/slides/abc123", wantKind: "slides", wantToken: "abc123"},
+		{name: "slides URL with query", input: "https://x.feishu.cn/slides/abc123?from=share", wantKind: "slides", wantToken: "abc123"},
+		{name: "slides URL with anchor", input: "https://x.feishu.cn/slides/abc123#p1", wantKind: "slides", wantToken: "abc123"},
+		{name: "wiki URL", input: "https://x.feishu.cn/wiki/wikcn123", wantKind: "wiki", wantToken: "wikcn123"},
+		{name: "trims whitespace", input: "  abc123  ", wantKind: "slides", wantToken: "abc123"},
+		{name: "empty", input: "", wantErr: "cannot be empty"},
+		{name: "blank", input: "   ", wantErr: "cannot be empty"},
+		{name: "unsupported url", input: "https://x.feishu.cn/docx/foo", wantErr: "unsupported"},
+		{name: "unsupported path", input: "foo/bar", wantErr: "unsupported"},
+		// Regression: /slides/ inside a query string must NOT be treated as a slides marker.
+		{name: "slides marker inside query", input: "https://x.feishu.cn/docx/foo?next=/slides/abc", wantErr: "unsupported"},
+		// Regression: /wiki/ as a path segment but not a prefix must not match.
+		{name: "wiki marker mid-path", input: "https://x.feishu.cn/docx/wiki/wikcn123", wantErr: "unsupported"},
+		// Regression: bare relative path containing wiki/ is not a wiki ref.
+		{name: "non-url wiki segment", input: "tmp/wiki/wikcn123", wantErr: "unsupported"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			got, err := parsePresentationRef(tt.input)
+			if tt.wantErr != "" {
+				if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
+					t.Fatalf("err = %v, want substring %q", err, tt.wantErr)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if got.Kind != tt.wantKind || got.Token != tt.wantToken {
+				t.Fatalf("got = %+v, want kind=%s token=%s", got, tt.wantKind, tt.wantToken)
+			}
+		})
+	}
+}
+
+func TestExtractImagePlaceholderPaths(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		in   []string
+		want []string
+	}{
+		{
+			name: "no placeholders",
+			in:   []string{`<slide><data><img src="https://x.com/a.png"/></data></slide>`},
+			want: nil,
+		},
+		{
+			name: "single placeholder",
+			in:   []string{`<slide><data><img src="@./pic.png" topLeftX="10"/></data></slide>`},
+			want: []string{"./pic.png"},
+		},
+		{
+			name: "single quotes",
+			in:   []string{`<img src='@./a.png'/>`},
+			want: []string{"./a.png"},
+		},
+		{
+			name: "dedup across slides",
+			in: []string{
+				`<slide><data><img src="@./shared.png"/></data></slide>`,
+				`<slide><data><img src="@./shared.png" topLeftX="100"/><img src="@./other.png"/></data></slide>`,
+			},
+			want: []string{"./shared.png", "./other.png"},
+		},
+		{
+			name: "ignores non-img src",
+			in:   []string{`<icon src="@./fake.png"/><img src="@./real.png"/>`},
+			want: []string{"./real.png"},
+		},
+		{
+			name: "preserves order of first occurrence",
+			in:   []string{`<img src="@b.png"/><img src="@a.png"/><img src="@b.png"/>`},
+			want: []string{"b.png", "a.png"},
+		},
+		{
+			// Regression: Go RE2 has no backreferences, so the regex captures
+			// opening and closing quotes independently. Mismatched pairs must
+			// be filtered out post-match instead of producing bogus paths.
+			name: "rejects mismatched quotes",
+			in:   []string{`<img src="@./oops.png'/>`},
+			want: nil,
+		},
+		{
+			// Regression: XML allows whitespace around `=`; placeholders in
+			// `src = "@..."` form must still be detected.
+			name: "tolerates whitespace around equals",
+			in:   []string{`<img src = "@./spaced.png" />`},
+			want: []string{"./spaced.png"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			got := extractImagePlaceholderPaths(tt.in)
+			if !reflect.DeepEqual(got, tt.want) {
+				t.Fatalf("got %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestReplaceImagePlaceholders(t *testing.T) {
+	t.Parallel()
+
+	tokens := map[string]string{
+		"./pic.png": "tok_abc",
+		"./b.png":   "tok_b",
+	}
+
+	tests := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{
+			name: "single replacement preserves siblings",
+			in:   `<img src="@./pic.png" topLeftX="10" width="100"/>`,
+			want: `<img src="tok_abc" topLeftX="10" width="100"/>`,
+		},
+		{
+			name: "multiple replacements",
+			in:   `<img src="@./pic.png"/><img src="@./b.png"/>`,
+			want: `<img src="tok_abc"/><img src="tok_b"/>`,
+		},
+		{
+			name: "single quotes",
+			in:   `<img src='@./pic.png'/>`,
+			want: `<img src='tok_abc'/>`,
+		},
+		{
+			name: "leaves unknown placeholder untouched",
+			in:   `<img src="@./missing.png"/>`,
+			want: `<img src="@./missing.png"/>`,
+		},
+		{
+			name: "leaves http url alone",
+			in:   `<img src="https://x.com/a.png"/>`,
+			want: `<img src="https://x.com/a.png"/>`,
+		},
+		{
+			name: "leaves bare token alone",
+			in:   `<img src="existing_token"/>`,
+			want: `<img src="existing_token"/>`,
+		},
+		{
+			// Regression: placeholders with whitespace around `=` must be
+			// rewritten too (XML permits the form). Surrounding whitespace
+			// is preserved so the rewritten attribute reads naturally.
+			name: "tolerates whitespace around equals",
+			in:   `<img src = "@./pic.png" topLeftX="10"/>`,
+			want: `<img src = "tok_abc" topLeftX="10"/>`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			got := replaceImagePlaceholders(tt.in, tokens)
+			if got != tt.want {
+				t.Fatalf("got %q\nwant %q", got, tt.want)
+			}
+		})
+	}
+}

shortcuts/slides/shortcuts.go

@@ -9,5 +9,6 @@ import "github.com/larksuite/cli/shortcuts/common"
 func Shortcuts() []common.Shortcut {
 	return []common.Shortcut{
 		SlidesCreate,
+		SlidesMediaUpload,
 	}
 }