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,
@@ -363,7 +368,14 @@ func TestCellsSetInput_MatrixPrecheck(t *testing.T) {
 				}
 				return
 			}
-			requireValidation(t, err, tc.wantContains)
+			ve := requireValidation(t, err, tc.wantContains)
+			// The precheck runs inside a batch sub-op, so the attribution is
+			// the flag the CALLER actually passed — --operations, with the
+			// sub-op's own --cells named in the message. A regression can keep
+			// the rendered text and lose either half.
+			if ve.Param != "--operations" {
+				t.Errorf("Param = %q, want %q", ve.Param, "--operations")
+			}
 		})
 	}
 }

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")
@@ -144,6 +144,15 @@ func TestCellsSetWrites(t *testing.T) {
 				t.Fatalf("message %q missing %q", ve.Message, want)
 			}
 		}
+		// The fold re-attributes to the outer flag and keeps the first inner
+		// issue as the cause; rendered text alone would not notice losing
+		// either.
+		if ve.Param != "--writes" {
+			t.Errorf("Param = %q, want %q", ve.Param, "--writes")
+		}
+		if ve.Cause == nil {
+			t.Error("Cause = nil, want the first inner issue preserved")
+		}
 	})
 
 	t.Run("item keys go through the vocabulary layer", func(t *testing.T) {
@@ -229,3 +238,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
@@ -295,3 +323,30 @@ func TestResolveCSVPathFromFileAlias_UnreadablePaths(t *testing.T) {
 		}
 	})
 }
+
+// TestCsvPutExecuteReportsForgottenAtSubstitution runs the whole +csv-put path
+// rather than csvForgottenAtWarnings on its own: the substitution is only
+// useful if it reaches the success envelope, and the direct unit test above
+// would keep passing if Execute stopped threading it through runtime.Out.
+func TestCsvPutExecuteReportsForgottenAtSubstitution(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)
+	}
+
+	stdout, err := runShortcutWithStubs(t, CsvPut, []string{
+		"--url", testURL, "--sheet-name", "S1", "--start-cell", "A1", "--csv", "./data.csv",
+	}, toolOutputStub(testToken, "write", `{"success":true}`))
+	if err != nil {
+		t.Fatalf("execute failed: %v\nstdout=%s", err, stdout)
+	}
+	data := decodeEnvelopeData(t, stdout)
+	warnings, _ := data["warnings"].([]interface{})
+	if len(warnings) != 1 {
+		t.Fatalf("expected the substitution note in the payload, got %#v", data)
+	}
+	if warning, _ := warnings[0].(string); !strings.Contains(warning, "@./data.csv") {
+		t.Errorf("warning should name the explicit @ form, got %q", warnings[0])
+	}
+}