feat(sheets): accept the payload spellings the 08-29..31 reflow rejected

shortcuts/sheets/batch_key_vocab_test.go

@@ -288,20 +288,25 @@ func TestCellsSetInput_MatrixPrecheck(t *testing.T) {
 			"+cells-clear",
 		},
 		{
-			"row count mismatch",
-			map[string]interface{}{"sheet_name": "S1", "range": "A1:B3",
+			// Overflow, not underflow: a payload that FITS inside the stated
+			// range is narrowed to it (fitCellsRange), so what the precheck
+			// still owns is a payload with nowhere to go.
+			"row count overflow",
+			map[string]interface{}{"sheet_name": "S1", "range": "A1:B1",
 				"cells": []interface{}{
 					[]interface{}{map[string]interface{}{"value": "a"}, map[string]interface{}{"value": "b"}},
+					[]interface{}{map[string]interface{}{"value": "c"}, map[string]interface{}{"value": "d"}},
 				}},
-			"--cells is 1 rows × 2 columns but --range \"A1:B3\" spans 3 rows × 2 columns",
+			"--cells is 2 rows × 2 columns but --range \"A1:B1\" spans 1 rows × 2 columns",
 		},
 		{
-			"column count mismatch",
-			map[string]interface{}{"sheet_name": "S1", "range": "A1:B1",
+			"column count overflow",
+			map[string]interface{}{"sheet_name": "S1", "range": "A1:A1",
 				"cells": []interface{}{
-					[]interface{}{map[string]interface{}{"value": "a"}},
+					[]interface{}{map[string]interface{}{"value": "a"}, map[string]interface{}{"value": "b"}},
+					[]interface{}{map[string]interface{}{"value": "c"}, map[string]interface{}{"value": "d"}},
 				}},
-			"--cells is 1 rows × 1 columns but --range \"A1:B1\" spans 1 rows × 2 columns",
+			"--cells is 2 rows × 2 columns but --range \"A1:A1\" spans 1 rows × 1 columns",
 		},
 		{
 			// Both axes off used to cost two round trips: rows failed first,

shortcuts/sheets/cells_set_writes_test.go

@@ -135,7 +135,7 @@ func TestCellsSetWrites(t *testing.T) {
 		// Both items pass the --writes schema (range+cells present) but fail
 		// deeper: item 0 a matrix mismatch, item 1 a missing sheet selector.
 		_, _, err := writes(`[
-			{"sheet_name":"S1","range":"A1:B2","cells":[[{"value":"x"}]]},
+			{"sheet_name":"S1","range":"A1:A1","cells":[[{"value":"x"},{"value":"z"}]]},
 			{"range":"C1","cells":[[{"value":"y"}]]}
 		]`)
 		ve := requireValidation(t, err, "--writes has 2 issues")
@@ -229,3 +229,43 @@ func TestCellsSetWrites(t *testing.T) {
 		}
 	})
 }
+
+// TestCellsSet_RangeNarrowedToPayload pins the narrowing: a payload that fits
+// inside the stated range is written at the same anchor, sized to itself,
+// and the difference is reported rather than silently applied.
+func TestCellsSet_RangeNarrowedToPayload(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name, stated, want string
+		cells              string
+	}{
+		{"a title against the range it will occupy once merged", "A1:D1", "A1:A1", `[[{"value":"标题"}]]`},
+		{"a block smaller on both axes", "A1:D4", "A1:B2", `[[{"value":1},{"value":2}],[{"value":3},{"value":4}]]`},
+		{"an exact fit is untouched", "A1:B1", "A1:B1", `[[{"value":1},{"value":2}]]`},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			stdout, _, err := runShortcutCapturingErr(t, CellsSet, []string{
+				"--url", testURL, "--sheet-name", "s", "--range", tc.stated,
+				"--cells", tc.cells, "--dry-run",
+			})
+			if err != nil {
+				t.Fatalf("payload fits, so it should be accepted: %v", err)
+			}
+			if !strings.Contains(strings.ReplaceAll(stdout, `\"`, `"`), `"range":"`+tc.want+`"`) {
+				t.Errorf("write should cover %s, got %q", tc.want, stdout)
+			}
+		})
+	}
+
+	t.Run("a payload with nowhere to go is still rejected", func(t *testing.T) {
+		t.Parallel()
+		// Growing the range would write over cells nobody named.
+		_, _, err := runShortcutCapturingErr(t, CellsSet, []string{
+			"--url", testURL, "--sheet-name", "s", "--range", "A1:A1",
+			"--cells", `[[{"value":1},{"value":2}]]`, "--dry-run",
+		})
+		requireValidation(t, err, `--range "A1:A1" spans`)
+	})
+}

shortcuts/sheets/csv_put_guard_test.go

@@ -22,33 +22,61 @@ func newCSVGuardRuntime(csvVal string) *common.RuntimeContext {
 	return &common.RuntimeContext{Cmd: cmd}
 }
 
-// TestGuardCSVValueIsNotFilePath covers the existing-file tier: a bare --csv
-// value naming a real file is a forgotten "@". The prescription names the fix
-// with a <path> placeholder — the untrusted value must not be spliced into
+// TestGuardCSVValueIsNotFilePath covers the existing-file tier for a value
+// that is NOT path-shaped: an inline value colliding with a real file name.
+// Reading it would be a guess, so both routes are prescribed — with a <path>
+// placeholder, since the untrusted value must not be spliced into
 // command-shaped text an agent would copy verbatim.
 func TestGuardCSVValueIsNotFilePath(t *testing.T) {
 	dir := t.TempDir()
 	cmdutil.TestChdir(t, dir)
-	if err := os.WriteFile("data.csv", []byte("a,b\n1,2\n"), 0644); err != nil {
+	if err := os.WriteFile("README.md", []byte("a,b\n1,2\n"), 0644); err != nil {
 		t.Fatal(err)
 	}
 
-	err := guardCSVValueIsNotFilePath(newCSVGuardRuntime("data.csv"))
+	err := guardCSVValueIsNotFilePath(newCSVGuardRuntime("README.md"))
 	ve := requireValidation(t, err, "existing file")
-	if !strings.Contains(ve.Message, `"data.csv"`) {
+	if !strings.Contains(ve.Message, `"README.md"`) {
 		t.Errorf("message should name the offending value as data, got: %q", ve.Message)
 	}
 	if !strings.Contains(ve.Message, "--csv @<path>") {
 		t.Errorf("message should prescribe the @ form via placeholder, got: %q", ve.Message)
 	}
-	if strings.Contains(ve.Message, "@data.csv") {
+	if strings.Contains(ve.Message, "@README.md") {
 		t.Errorf("message must not splice the value into a command fragment, got: %q", ve.Message)
 	}
 	if ve.Param != "--csv" {
 		t.Errorf("param = %q, want --csv", ve.Param)
 	}
 }
 
+// TestGuardCSVValueReadsForgottenAtPath covers the tier the 08-29..31 reflow
+// added: a path-SHAPED value naming a real file is a forgotten "@" and nothing
+// else, so the file is read and the substitution is reported in the envelope
+// instead of costing a round trip.
+func TestGuardCSVValueReadsForgottenAtPath(t *testing.T) {
+	dir := t.TempDir()
+	cmdutil.TestChdir(t, dir)
+	if err := os.WriteFile("data.csv", []byte("a,b\n1,2\n"), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	runtime := newCSVGuardRuntime("./data.csv")
+	if err := guardCSVValueIsNotFilePath(runtime); err != nil {
+		t.Fatalf("a path-shaped existing file should be read, got: %v", err)
+	}
+	if got := runtime.Str("csv"); got != "a,b\n1,2\n" {
+		t.Errorf("--csv = %q, want the file contents", got)
+	}
+	if !runtime.InputResolvedFromSource("csv") {
+		t.Error("the value came from a file, so it must be marked resolved")
+	}
+	warnings := csvForgottenAtWarnings(runtime)
+	if len(warnings) != 1 || !strings.Contains(warnings[0], "@./data.csv") {
+		t.Errorf("warnings = %v, want one naming the explicit @ form", warnings)
+	}
+}
+
 // TestGuardCSVValueIsNotFilePath_MissingButPathShaped covers the second tier.
 // A path that doesn't resolve used to pass through and be written into the
 // cell verbatim — a wrong value with a success exit code. The common source is

shortcuts/sheets/execute_paths_test.go

@@ -6,6 +6,7 @@ package sheets
 import (
 	"encoding/json"
 	"errors"
+	"net/http"
 	"strings"
 	"testing"
 
@@ -1185,3 +1186,139 @@ func decodeRawEnvelopeBody(t *testing.T, raw []byte) map[string]interface{} {
 	}
 	return body
 }
+
+// TestExecute_TransientReadRetry pins the read-only retry: an identical read
+// is reissued when the tool answers with its own timeout wording, and the
+// write path is never reissued because this API has no idempotency key.
+func TestExecute_TransientReadRetry(t *testing.T) {
+	t.Parallel()
+
+	timeoutBody := map[string]interface{}{
+		"code": 1310299, "msg": "server time out error", "data": map[string]interface{}{},
+	}
+
+	t.Run("a read retries past a tool timeout", func(t *testing.T) {
+		t.Parallel()
+		parent, stdout, _, reg := newTestRig(t, WorkbookInfo)
+		calls := 0
+		count := func(*http.Request) { calls++ }
+		readURL := "/open-apis/sheet_ai/v2/spreadsheets/" + testToken + "/tools/invoke_read"
+		// Stubs are served in registration order, so the first try fails and
+		// the retry meets the success stub.
+		reg.Register(&httpmock.Stub{Method: "POST", URL: readURL, Body: timeoutBody, OnMatch: count})
+		reg.Register(&httpmock.Stub{Method: "POST", URL: readURL, OnMatch: count, Body: map[string]interface{}{
+			"code": 0, "msg": "success",
+			"data": map[string]interface{}{"output": `{"sheets":[]}`},
+		}})
+		parent.SetArgs([]string{"+workbook-info", "--url", testURL})
+		if err := parent.Execute(); err != nil {
+			t.Fatalf("the second try should succeed, got: %v", err)
+		}
+		if calls != 2 {
+			t.Errorf("calls = %d, want 2 (one retry)", calls)
+		}
+		if !strings.Contains(stdout.String(), `"ok": true`) {
+			t.Errorf("stdout should carry the successful read, got %q", stdout.String())
+		}
+	})
+
+	t.Run("a persistent failure surfaces after the attempts are spent", func(t *testing.T) {
+		t.Parallel()
+		parent, _, _, reg := newTestRig(t, WorkbookInfo)
+		calls := 0
+		reg.Register(&httpmock.Stub{
+			Method: "POST", URL: "/open-apis/sheet_ai/v2/spreadsheets/" + testToken + "/tools/invoke_read",
+			Body: timeoutBody, Reusable: true, OnMatch: func(*http.Request) { calls++ },
+		})
+		parent.SetArgs([]string{"+workbook-info", "--url", testURL})
+		if err := parent.Execute(); err == nil {
+			t.Fatal("expected the failure to surface")
+		}
+		if calls != readRetryAttempts {
+			t.Errorf("calls = %d, want %d", calls, readRetryAttempts)
+		}
+	})
+
+	t.Run("a write is never reissued", func(t *testing.T) {
+		t.Parallel()
+		parent, _, _, reg := newTestRig(t, CellsSet)
+		calls := 0
+		reg.Register(&httpmock.Stub{
+			Method: "POST", URL: "/open-apis/sheet_ai/v2/spreadsheets/" + testToken + "/tools/invoke_write",
+			Body: timeoutBody, Reusable: true, OnMatch: func(*http.Request) { calls++ },
+		})
+		parent.SetArgs([]string{"+cells-set", "--url", testURL, "--sheet-name", "s",
+			"--range", "A1:A1", "--cells", `[[{"value":"x"}]]`})
+		if err := parent.Execute(); err == nil {
+			t.Fatal("expected the failure to surface")
+		}
+		// A create that timed out after the backend committed it must not be
+		// committed twice.
+		if calls != 1 {
+			t.Errorf("calls = %d, want 1 (writes are not retried)", calls)
+		}
+	})
+}
+
+// TestExecute_MergedRegionHints pins the prescriptions on the two merged-cell
+// rejections. The backend names the obstacle but never in A1 notation and
+// never with the command that clears it.
+func TestExecute_MergedRegionHints(t *testing.T) {
+	t.Parallel()
+	for _, tc := range []struct {
+		name, serverMsg, wantHint string
+	}{
+		{
+			name:      "merge overlapping an existing region",
+			serverMsg: "batch_update: 0 succeeded, 1 failed — operations[0] (merge_cells): Range A1:J1 overlaps existing merged cells: [0,0-0,6]. Unmerge them first (operation=unmerge) before merging.",
+			wantHint:  `+cells-unmerge --range "A1:G1"`,
+		},
+		{
+			name:      "write landing inside a merged region",
+			serverMsg: "cell at row 0, col 1 is inside a merged region (top-left: A1). Writing to non-top-left cells of merged regions is not supported.",
+			wantHint:  "top-left cell",
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			parent, _, _, reg := newTestRig(t, CellsSet)
+			reg.Register(&httpmock.Stub{
+				Method: "POST", URL: "/open-apis/sheet_ai/v2/spreadsheets/" + testToken + "/tools/invoke_write",
+				Body: map[string]interface{}{
+					"code": 900015206, "msg": tc.serverMsg, "data": map[string]interface{}{},
+				},
+			})
+			parent.SetArgs([]string{"+cells-set", "--url", testURL, "--sheet-name", "s",
+				"--range", "B2:B2", "--cells", `[[{"value":"x"}]]`})
+			err := parent.Execute()
+			if err == nil {
+				t.Fatal("expected the merge conflict to surface")
+			}
+			p, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("err = %v, want a typed problem", err)
+			}
+			if !strings.Contains(p.Hint, tc.wantHint) {
+				t.Errorf("hint = %q, want it to carry %q", p.Hint, tc.wantHint)
+			}
+		})
+	}
+
+	t.Run("an unrelated failure gets no merge hint", func(t *testing.T) {
+		t.Parallel()
+		parent, _, _, reg := newTestRig(t, CellsSet)
+		reg.Register(&httpmock.Stub{
+			Method: "POST", URL: "/open-apis/sheet_ai/v2/spreadsheets/" + testToken + "/tools/invoke_write",
+			Body: map[string]interface{}{
+				"code": 900015206, "msg": "parameter validation failed", "data": map[string]interface{}{},
+			},
+		})
+		parent.SetArgs([]string{"+cells-set", "--url", testURL, "--sheet-name", "s",
+			"--range", "B2:B2", "--cells", `[[{"value":"x"}]]`})
+		err := parent.Execute()
+		p, _ := errs.ProblemOf(err)
+		if p != nil && strings.Contains(p.Hint, "+cells-unmerge") {
+			t.Errorf("hint = %q, want no merge prescription", p.Hint)
+		}
+	})
+}