feat(docs): add non-destructive image anchors (#843)

steipete · web-flow · commit 83f51c60f183 · 2026-06-18T12:54:42.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 ### Added
 
+- Docs: add non-destructive `insert-image --before` and `--after` anchors while clarifying that `--at` replaces its placeholder. (#839) — thanks @sebsnyk.
 - Slides: allow `insert-image` and `replace-slide` to use public HTTPS image URLs without temporary Drive sharing. (#825) — thanks @sebsnyk.
 - Slides: add structured element geometry, styled text runs, table-cell content, image source URLs, native presentation metadata, and read-only text location with exact UTF-16 ranges. (#822) — thanks @sebsnyk.
 - Slides: add range-scoped styling, links, bullets, and object-scoped replacement; `replace-text` now requires explicit `--object`, `--page`, or `--all` scope instead of silently changing the whole deck. (#823, #835) — thanks @sebsnyk.
diff --git a/docs/commands/gog-docs-insert-image.md b/docs/commands/gog-docs-insert-image.md
@@ -20,7 +20,9 @@ gog docs (doc) insert-image <docId> [flags]
 | --- | --- | --- | --- |
 | `--access-token` | `string` |  | Use provided access token directly (bypasses stored refresh tokens; token expires in ~1h) |
 | `-a`<br>`--account`<br>`--acct` | `string` |  | Account email, alias, or auto for authenticated Google API commands |
-| `--at` | `string` | end | Placeholder text to replace, or 'end' to append |
+| `--after` | `*string` |  | Insert after the first literal text match without deleting it |
+| `--at` | `*string` |  | Placeholder text to delete and replace, or 'end' to append |
+| `--before` | `*string` |  | Insert before the first literal text match without deleting it |
 | `--client` | `string` |  | OAuth client name (selects stored credentials + token bucket) |
 | `--color` | `string` | auto | Color output: auto\|always\|never |
 | `--disable-commands` | `string` |  | Comma-separated list of disabled commands; dot paths allowed |
diff --git a/docs/docs-editing.md b/docs/docs-editing.md
@@ -178,7 +178,9 @@ gog docs insert-image <docId> --url https://example.com/chart.png --at end
 
 Use `--file` for local PNG, JPEG, or GIF input. Local files are uploaded to
 Drive and may require link sharing; `--url` leaves Drive permissions unchanged.
-Both modes accept `--tab`, `--width`, and `--height`.
+Both modes accept `--tab`, `--width`, and `--height`. Omit anchor flags or use
+`--at end` to append. `--at <text>` deletes and replaces the first literal text
+match; use `--before <text>` or `--after <text>` to preserve the anchor text.
 
 Command page:
 
diff --git a/internal/cmd/docs_insert_image.go b/internal/cmd/docs_insert_image.go
@@ -24,7 +24,9 @@ type DocsInsertImageCmd struct {
 	DocID        string  `arg:"" name:"docId" help:"Doc ID"`
 	File         string  `name:"file" help:"Local PNG, JPEG, or GIF image to upload and insert" type:"existingfile"`
 	URL          string  `name:"url" help:"Public HTTPS image URL to insert directly"`
-	At           string  `name:"at" help:"Placeholder text to replace, or 'end' to append" default:"end"`
+	At           *string `name:"at" help:"Placeholder text to delete and replace, or 'end' to append"`
+	Before       *string `name:"before" help:"Insert before the first literal text match without deleting it"`
+	After        *string `name:"after" help:"Insert after the first literal text match without deleting it"`
 	Width        float64 `name:"width" help:"Image width in points; default 468pt" default:"468"`
 	Height       float64 `name:"height" help:"Image height in points (optional; width-only preserves aspect ratio)"`
 	Parent       string  `name:"parent" help:"Drive folder ID for the uploaded image"`
@@ -53,6 +55,19 @@ type docsInsertImageSource struct {
 	imageURL  string
 }
 
+type docsImageAnchorMode string
+
+const (
+	docsImageAnchorReplace docsImageAnchorMode = "at"
+	docsImageAnchorBefore  docsImageAnchorMode = "before"
+	docsImageAnchorAfter   docsImageAnchorMode = "after"
+)
+
+type docsImageTarget struct {
+	anchor string
+	mode   docsImageAnchorMode
+}
+
 func (c *DocsInsertImageCmd) Run(ctx context.Context, flags *RootFlags) error {
 	docID := strings.TrimSpace(c.DocID)
 	if docID == "" {
@@ -65,16 +80,16 @@ func (c *DocsInsertImageCmd) Run(ctx context.Context, flags *RootFlags) error {
 	if err != nil {
 		return err
 	}
-	at := strings.TrimSpace(c.At)
-	if at == "" {
-		return usage("empty --at")
+	target, err := c.resolveTarget()
+	if err != nil {
+		return err
 	}
 	dryRunPayload := map[string]any{
-		"documentId": docID,
-		"at":         at,
-		"width":      c.Width,
-		"height":     c.Height,
-		"tab":        c.Tab,
+		"documentId":        docID,
+		"width":             c.Width,
+		"height":            c.Height,
+		"tab":               c.Tab,
+		string(target.mode): target.anchor,
 	}
 	if source.imageURL != "" {
 		dryRunPayload["url"] = source.imageURL
@@ -105,20 +120,48 @@ func (c *DocsInsertImageCmd) Run(ctx context.Context, flags *RootFlags) error {
 
 	var result docsInsertImageResult
 	if source.imageURL != "" {
-		result, err = c.runURL(ctx, docsSvc, docID, source.imageURL, at)
+		result, err = c.runURL(ctx, docsSvc, docID, source.imageURL, target)
 	} else {
 		driveSvc, driveErr := driveService(ctx, account)
 		if driveErr != nil {
 			return driveErr
 		}
-		result, err = c.runFile(ctx, docsSvc, driveSvc, docID, source.localPath, source.name, source.mimeType, at)
+		result, err = c.runFile(ctx, docsSvc, driveSvc, docID, source.localPath, source.name, source.mimeType, target)
 	}
 	if err != nil {
 		return err
 	}
 	return writeDocsInsertImageResult(ctx, result)
 }
 
+func (c *DocsInsertImageCmd) resolveTarget() (docsImageTarget, error) {
+	set := 0
+	for _, value := range []*string{c.At, c.Before, c.After} {
+		if value != nil {
+			set++
+		}
+	}
+	if set > 1 {
+		return docsImageTarget{}, usage("--at, --before, and --after are mutually exclusive")
+	}
+
+	target := docsImageTarget{anchor: docsAtIndexEnd, mode: docsImageAnchorReplace}
+	switch {
+	case c.At != nil:
+		target.anchor = strings.TrimSpace(*c.At)
+	case c.Before != nil:
+		target.anchor = strings.TrimSpace(*c.Before)
+		target.mode = docsImageAnchorBefore
+	case c.After != nil:
+		target.anchor = strings.TrimSpace(*c.After)
+		target.mode = docsImageAnchorAfter
+	}
+	if target.anchor == "" {
+		return docsImageTarget{}, usage(fmt.Sprintf("empty --%s", target.mode))
+	}
+	return target, nil
+}
+
 func (c *DocsInsertImageCmd) resolveSource() (docsInsertImageSource, error) {
 	localFile := strings.TrimSpace(c.File)
 	imageURL := strings.TrimSpace(c.URL)
@@ -198,12 +241,12 @@ func writeDocsInsertImageResult(ctx context.Context, result docsInsertImageResul
 	return nil
 }
 
-func (c *DocsInsertImageCmd) runURL(ctx context.Context, docsSvc *docs.Service, docID, imageURL, at string) (docsInsertImageResult, error) {
+func (c *DocsInsertImageCmd) runURL(ctx context.Context, docsSvc *docs.Service, docID, imageURL string, target docsImageTarget) (docsInsertImageResult, error) {
 	result := docsInsertImageResult{sourceURL: imageURL}
-	return c.insertImageURL(ctx, docsSvc, docID, imageURL, at, result)
+	return c.insertImageURL(ctx, docsSvc, docID, imageURL, target, result)
 }
 
-func (c *DocsInsertImageCmd) runFile(ctx context.Context, docsSvc *docs.Service, driveSvc *drive.Service, docID, localPath, name, mimeType, at string) (result docsInsertImageResult, err error) {
+func (c *DocsInsertImageCmd) runFile(ctx context.Context, docsSvc *docs.Service, driveSvc *drive.Service, docID, localPath, name, mimeType string, target docsImageTarget) (result docsInsertImageResult, err error) {
 	uploaded, err := uploadDocsInlineImage(ctx, driveSvc, localPath, name, mimeType, strings.TrimSpace(c.Parent))
 	if err != nil {
 		return result, err
@@ -218,7 +261,7 @@ func (c *DocsInsertImageCmd) runFile(ctx context.Context, docsSvc *docs.Service,
 		Do()
 	if err != nil {
 		if strings.EqualFold(c.OnRestricted, "link") && isDrivePublicSharingRestricted(err) {
-			return c.insertRestrictedImageFallback(ctx, docsSvc, docID, uploaded, at, result)
+			return c.insertRestrictedImageFallback(ctx, docsSvc, docID, uploaded, target, result)
 		}
 		return result, fmt.Errorf("share uploaded image publicly: %w", err)
 	}
@@ -243,11 +286,11 @@ func (c *DocsInsertImageCmd) runFile(ctx context.Context, docsSvc *docs.Service,
 	}()
 
 	imageURL := driveImageDownloadURL(uploaded.Id)
-	return c.insertImageURL(ctx, docsSvc, docID, imageURL, at, result)
+	return c.insertImageURL(ctx, docsSvc, docID, imageURL, target, result)
 }
 
-func (c *DocsInsertImageCmd) insertImageURL(ctx context.Context, docsSvc *docs.Service, docID, imageURL, at string, result docsInsertImageResult) (docsInsertImageResult, error) {
-	reqs, index, tabID, err := c.buildInsertRequests(ctx, docsSvc, docID, at, imageURL)
+func (c *DocsInsertImageCmd) insertImageURL(ctx context.Context, docsSvc *docs.Service, docID, imageURL string, target docsImageTarget, result docsInsertImageResult) (docsInsertImageResult, error) {
+	reqs, index, tabID, err := c.buildInsertRequests(ctx, docsSvc, docID, target, imageURL)
 	if err != nil {
 		return result, err
 	}
@@ -261,12 +304,12 @@ func (c *DocsInsertImageCmd) insertImageURL(ctx context.Context, docsSvc *docs.S
 	return result, nil
 }
 
-func (c *DocsInsertImageCmd) insertRestrictedImageFallback(ctx context.Context, docsSvc *docs.Service, docID string, uploaded *drive.File, at string, result docsInsertImageResult) (docsInsertImageResult, error) {
+func (c *DocsInsertImageCmd) insertRestrictedImageFallback(ctx context.Context, docsSvc *docs.Service, docID string, uploaded *drive.File, target docsImageTarget, result docsInsertImageResult) (docsInsertImageResult, error) {
 	link := uploaded.WebViewLink
 	if link == "" {
 		link = bestEffortWebURL("drive", uploaded.Id)
 	}
-	reqs, index, tabID, err := c.buildLinkFallbackRequests(ctx, docsSvc, docID, at, link)
+	reqs, index, tabID, err := c.buildLinkFallbackRequests(ctx, docsSvc, docID, target, link)
 	if err != nil {
 		return result, err
 	}
@@ -305,8 +348,8 @@ func uploadDocsInlineImage(ctx context.Context, svc *drive.Service, localPath, n
 	return created, nil
 }
 
-func (c *DocsInsertImageCmd) buildInsertRequests(ctx context.Context, svc *docs.Service, docID, at, imageURL string) ([]*docs.Request, int64, string, error) {
-	index, placeholder, tabID, err := c.resolveImageTarget(ctx, svc, docID, at)
+func (c *DocsInsertImageCmd) buildInsertRequests(ctx context.Context, svc *docs.Service, docID string, target docsImageTarget, imageURL string) ([]*docs.Request, int64, string, error) {
+	index, placeholder, tabID, err := c.resolveImageTarget(ctx, svc, docID, target)
 	if err != nil {
 		return nil, 0, "", err
 	}
@@ -331,8 +374,8 @@ func (c *DocsInsertImageCmd) buildInsertRequests(ctx context.Context, svc *docs.
 	return reqs, index, tabID, nil
 }
 
-func (c *DocsInsertImageCmd) buildLinkFallbackRequests(ctx context.Context, svc *docs.Service, docID, at, link string) ([]*docs.Request, int64, string, error) {
-	index, placeholder, tabID, err := c.resolveImageTarget(ctx, svc, docID, at)
+func (c *DocsInsertImageCmd) buildLinkFallbackRequests(ctx context.Context, svc *docs.Service, docID string, target docsImageTarget, link string) ([]*docs.Request, int64, string, error) {
+	index, placeholder, tabID, err := c.resolveImageTarget(ctx, svc, docID, target)
 	if err != nil {
 		return nil, 0, "", err
 	}
@@ -349,8 +392,8 @@ func (c *DocsInsertImageCmd) buildLinkFallbackRequests(ctx context.Context, svc
 	return reqs, index, tabID, nil
 }
 
-func (c *DocsInsertImageCmd) resolveImageTarget(ctx context.Context, svc *docs.Service, docID, at string) (int64, *docsedit.TextRange, string, error) {
-	if strings.EqualFold(at, docsAtIndexEnd) {
+func (c *DocsInsertImageCmd) resolveImageTarget(ctx context.Context, svc *docs.Service, docID string, target docsImageTarget) (int64, *docsedit.TextRange, string, error) {
+	if target.mode == docsImageAnchorReplace && strings.EqualFold(target.anchor, docsAtIndexEnd) {
 		endIndex, tabID, err := docsTargetEndIndexAndTabID(ctx, svc, docID, c.Tab)
 		if err != nil {
 			return 0, nil, "", err
@@ -361,15 +404,23 @@ func (c *DocsInsertImageCmd) resolveImageTarget(ctx context.Context, svc *docs.S
 	if err != nil {
 		return 0, nil, "", err
 	}
-	matches := docsedit.FindTextRanges(loaded.target, at, docsedit.SearchOptions{
+	matches := docsedit.FindTextRanges(loaded.target, target.anchor, docsedit.SearchOptions{
 		MatchCase:            true,
 		PreserveHTMLEntities: true,
 		RequireTextSegment:   true,
 	})
 	if len(matches) == 0 {
-		return 0, nil, "", fmt.Errorf("placeholder not found: %q", at)
+		return 0, nil, "", fmt.Errorf("anchor not found: %q", target.anchor)
+	}
+	match := matches[0]
+	switch target.mode {
+	case docsImageAnchorBefore:
+		return match.StartIndex, nil, loaded.tabID, nil
+	case docsImageAnchorAfter:
+		return match.EndIndex, nil, loaded.tabID, nil
+	default:
+		return match.StartIndex, &match, loaded.tabID, nil
 	}
-	return matches[0].StartIndex, &matches[0], loaded.tabID, nil
 }
 
 func isDocsInsertImageMime(mimeType string) bool {
diff --git a/internal/cmd/docs_insert_image_test.go b/internal/cmd/docs_insert_image_test.go
@@ -50,6 +50,41 @@ func TestDocsInsertImageResolveSourceURL(t *testing.T) {
 	}
 }
 
+func TestDocsInsertImageResolveTarget(t *testing.T) {
+	value := func(s string) *string { return &s }
+	tests := []struct {
+		name       string
+		cmd        DocsInsertImageCmd
+		wantAnchor string
+		wantMode   docsImageAnchorMode
+		wantErr    string
+	}{
+		{name: "default end", cmd: DocsInsertImageCmd{}, wantAnchor: "end", wantMode: docsImageAnchorReplace},
+		{name: "replace", cmd: DocsInsertImageCmd{At: value(" marker ")}, wantAnchor: "marker", wantMode: docsImageAnchorReplace},
+		{name: "before", cmd: DocsInsertImageCmd{Before: value(" marker ")}, wantAnchor: "marker", wantMode: docsImageAnchorBefore},
+		{name: "after", cmd: DocsInsertImageCmd{After: value(" marker ")}, wantAnchor: "marker", wantMode: docsImageAnchorAfter},
+		{name: "empty", cmd: DocsInsertImageCmd{Before: value(" ")}, wantErr: "empty --before"},
+		{name: "conflict", cmd: DocsInsertImageCmd{At: value("a"), After: value("b")}, wantErr: "mutually exclusive"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			target, err := tt.cmd.resolveTarget()
+			if tt.wantErr != "" {
+				if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
+					t.Fatalf("resolveTarget() error = %v, want %q", err, tt.wantErr)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("resolveTarget(): %v", err)
+			}
+			if target.anchor != tt.wantAnchor || target.mode != tt.wantMode {
+				t.Fatalf("resolveTarget() = %#v", target)
+			}
+		})
+	}
+}
+
 func TestDocsInsertImageURLRunSkipsDrive(t *testing.T) {
 	t.Parallel()
 
@@ -136,12 +171,13 @@ func TestDocsInsertImageURLDryRunSkipsServices(t *testing.T) {
 		Op      string `json:"op"`
 		Request struct {
 			URL string `json:"url"`
+			At  string `json:"at"`
 		} `json:"request"`
 	}
 	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
 		t.Fatalf("decode dry-run output: %v\n%s", err, stdout.String())
 	}
-	if payload.Op != "docs.insert-image" || payload.Request.URL != "https://example.com/image.png" {
+	if payload.Op != "docs.insert-image" || payload.Request.URL != "https://example.com/image.png" || payload.Request.At != "end" {
 		t.Fatalf("unexpected dry-run output: %#v", payload)
 	}
 }
diff --git a/internal/cmd/docs_remaining_features_test.go b/internal/cmd/docs_remaining_features_test.go
@@ -332,7 +332,7 @@ func TestDocsSmartChipCommandsBuildRequests(t *testing.T) {
 }
 
 func TestDocsInsertImageBuildsPlaceholderReplacement(t *testing.T) {
-	cmd := &DocsInsertImageCmd{At: "IMG_HERE", Width: 320}
+	cmd := &DocsInsertImageCmd{Width: 320}
 	docSvc, cleanup := newDocsServiceForTest(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.Method != http.MethodGet || !strings.Contains(r.URL.Path, "/v1/documents/doc1") {
 			http.NotFound(w, r)
@@ -343,7 +343,8 @@ func TestDocsInsertImageBuildsPlaceholderReplacement(t *testing.T) {
 	}))
 	defer cleanup()
 
-	reqs, index, tabID, err := cmd.buildInsertRequests(context.Background(), docSvc, "doc1", "IMG_HERE", "https://example.com/i.png")
+	target := docsImageTarget{anchor: "IMG_HERE", mode: docsImageAnchorReplace}
+	reqs, index, tabID, err := cmd.buildInsertRequests(context.Background(), docSvc, "doc1", target, "https://example.com/i.png")
 	if err != nil {
 		t.Fatalf("buildInsertRequests: %v", err)
 	}
@@ -357,3 +358,48 @@ func TestDocsInsertImageBuildsPlaceholderReplacement(t *testing.T) {
 		t.Fatalf("unexpected image request: %#v", reqs[1].InsertInlineImage)
 	}
 }
+
+func TestDocsInsertImageBuildsNonDestructiveAnchorInsertions(t *testing.T) {
+	cmd := &DocsInsertImageCmd{Width: 320}
+	docSvc, cleanup := newDocsServiceForTest(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet || !strings.Contains(r.URL.Path, "/v1/documents/doc1") {
+			http.NotFound(w, r)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(docBodyWithText("before IMG_HERE after\n"))
+	}))
+	defer cleanup()
+
+	for _, tc := range []struct {
+		name  string
+		mode  docsImageAnchorMode
+		index int64
+	}{
+		{name: "before", mode: docsImageAnchorBefore, index: 8},
+		{name: "after", mode: docsImageAnchorAfter, index: 16},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			target := docsImageTarget{anchor: "IMG_HERE", mode: tc.mode}
+			reqs, index, _, err := cmd.buildInsertRequests(context.Background(), docSvc, "doc1", target, "https://example.com/i.png")
+			if err != nil {
+				t.Fatalf("buildInsertRequests: %v", err)
+			}
+			if index != tc.index || len(reqs) != 1 || reqs[0].InsertInlineImage == nil {
+				t.Fatalf("index=%d requests=%#v", index, reqs)
+			}
+			if reqs[0].InsertInlineImage.Location.Index != tc.index {
+				t.Fatalf("image location = %#v", reqs[0].InsertInlineImage.Location)
+			}
+		})
+	}
+
+	target := docsImageTarget{anchor: "IMG_HERE", mode: docsImageAnchorAfter}
+	reqs, index, _, err := cmd.buildLinkFallbackRequests(context.Background(), docSvc, "doc1", target, "https://example.com/file")
+	if err != nil {
+		t.Fatalf("buildLinkFallbackRequests: %v", err)
+	}
+	if index != 16 || len(reqs) != 1 || reqs[0].InsertText == nil || reqs[0].InsertText.Location.Index != 16 {
+		t.Fatalf("index=%d requests=%#v", index, reqs)
+	}
+}
