fix(sheets): validate insert formatting inheritance

steipete · steipete · commit d1da0e673c34 · 2026-05-30T18:51:29.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,7 @@
 
 - Gmail: keep label IDs case-sensitive during label resolution and duplicate-name checks while still matching label names case-insensitively.
 - Gmail: clarify that `gmail drafts delete` permanently deletes drafts and cannot be recovered. (#656, #659) — thanks @chrischall.
+- Sheets: add `--inherit-from-before` to `sheets insert` so callers can choose whether inserted rows/columns inherit formatting from the preceding or following neighbor. (#655, #658) — thanks @chrischall.
 - Docs: update the bundled `gog` agent skill to preserve broad user OAuth scopes during reauth and rely on command guards for scoped execution.
 
 ## 0.19.0 - 2026-05-22
diff --git a/docs/commands/gog-sheets-insert.md b/docs/commands/gog-sheets-insert.md
@@ -31,7 +31,7 @@ gog sheets (sheet) insert <spreadsheetId> <sheet> <dimension> <start> [flags]
 | `--gmail-no-send` | `bool` | false | Block Gmail send operations (agent safety) |
 | `-h`<br>`--help` | `kong.helpFlag` |  | Show context-sensitive help. |
 | `--home` | `string` |  | Override gogcli config/data/state/cache root (equivalent to GOG_HOME) |
-| `--inherit-from-before` | `*bool` |  | Inherit number format / styling from the adjacent row/column. Defaults to true with --after, false otherwise; set to false to insert with plain formatting. |
+| `--inherit-from-before` | `*bool` |  | Inherit number format / styling from the row/column before the insertion. Defaults to true with --after, false otherwise; false inherits from the row/column after the insertion. |
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
diff --git a/internal/cmd/sheets_insert.go b/internal/cmd/sheets_insert.go
@@ -20,7 +20,7 @@ type SheetsInsertCmd struct {
 	After         bool   `name:"after" help:"Insert after the position instead of before"`
 	// *bool so an unset flag keeps the historical default (inherit only when
 	// --after); passing --inherit-from-before[=false] overrides it explicitly.
-	InheritFromBefore *bool `name:"inherit-from-before" help:"Inherit number format / styling from the adjacent row/column. Defaults to true with --after, false otherwise; set to false to insert with plain formatting."`
+	InheritFromBefore *bool `name:"inherit-from-before" help:"Inherit number format / styling from the row/column before the insertion. Defaults to true with --after, false otherwise; false inherits from the row/column after the insertion."`
 }
 
 func (c *SheetsInsertCmd) Run(ctx context.Context, flags *RootFlags) error {
@@ -67,6 +67,9 @@ func (c *SheetsInsertCmd) Run(ctx context.Context, flags *RootFlags) error {
 	if c.InheritFromBefore != nil {
 		inheritFromBefore = *c.InheritFromBefore
 	}
+	if inheritFromBefore && startIndex == 0 {
+		return usagef("cannot inherit from the previous %s when inserting at position 1", dimLabel)
+	}
 
 	if dryRunErr := dryRunExit(ctx, flags, "sheets.insert", map[string]any{
 		"spreadsheet_id":      spreadsheetID,
diff --git a/internal/cmd/sheets_insert_test.go b/internal/cmd/sheets_insert_test.go
@@ -124,7 +124,7 @@ func TestSheetsInsertCmd(t *testing.T) {
 		}
 	})
 
-	t.Run("insert after without inheriting formatting", func(t *testing.T) {
+	t.Run("insert after inheriting from following dimension", func(t *testing.T) {
 		gotInsert = nil
 		cmd := &SheetsInsertCmd{}
 		if err := runKong(t, cmd, []string{
@@ -135,7 +135,8 @@ func TestSheetsInsertCmd(t *testing.T) {
 		if gotInsert == nil {
 			t.Fatal("expected insertDimension request")
 		}
-		// --after would default inheritFromBefore=true; the explicit flag overrides it.
+		// --after would default inheritFromBefore=true; the explicit flag overrides it
+		// so the API inherits from the following adjacent row/column instead.
 		if gotInsert.InheritFromBefore {
 			t.Fatal("expected inheritFromBefore=false when --inherit-from-before=false overrides --after")
 		}
@@ -158,6 +159,23 @@ func TestSheetsInsertCmd(t *testing.T) {
 		}
 	})
 
+	t.Run("reject inherit from before at first row", func(t *testing.T) {
+		gotInsert = nil
+		cmd := &SheetsInsertCmd{}
+		err := runKong(t, cmd, []string{
+			"s1", "Data", "rows", "1", "--inherit-from-before",
+		}, ctx, flags)
+		if err == nil {
+			t.Fatal("expected error")
+		}
+		if !strings.Contains(err.Error(), "cannot inherit from the previous row") {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if gotInsert != nil {
+			t.Fatal("did not expect API request")
+		}
+	})
+
 	t.Run("insert cols before", func(t *testing.T) {
 		gotInsert = nil
 		cmd := &SheetsInsertCmd{}
