feat(sheets): add table manipulation commands with smart sheet resolution

[Pedrohgv]

feat(sheets): add table manipulation commands with smart sheet resolution

What is this feature?

Adds comprehensive Google Sheets Tables API support to gogcli. Tables are structured Excel-like data containers with typed columns (dropdowns, dates, percentages), headers, footers, and named references. This feature enables programmatic table creation, data manipulation, and aggregation via the CLI.

Key Features

• 7 table commands — create, list, get, update, append, clear, delete
• Smart sheet resolution — create and append tables on any sheet (Sheet1, TestSheet, SalesData)
• Column types — TEXT, DOUBLE, CURRENCY, DATE, DROPDOWN, PERCENT, and more
• Footer formulas — automatic preservation when tables expand
• Named references — use =SUM(TableName[Column]) syntax for formulas
• Auto-expansion — tables grow automatically when appending beyond capacity
• Data validation — dropdown columns with custom lists
• JSON output — machine-readable for scripting

Usage Examples

# Create a table with dropdown and footer
gog sheets table create SPREADSHEET_ID Sheet1!A1:D10 \
  --name "Project Tracker" \
  --columns-json '[{"columnName":"Task","columnType":"TEXT"},{"columnName":"Status","columnType":"DROPDOWN","dataValidation":{"condition":{"type":"ONE_OF_LIST","values":[{"userEnteredValue":"Done"},{"userEnteredValue":"In Progress"}]}}},{"columnName":"Due","columnType":"DATE"},{"columnName":"Complete","columnType":"PERCENT"}]' \
  --footer

# Add data (auto-expands if needed)
gog sheets table append SPREADSHEET_ID TABLE_ID \
  --values-json '[["Design","In Progress","2024-01-15","75%"],["Implement","Done","2024-01-10","100%"]]'

# Add aggregation formulas to footer
gog sheets update SPREADSHEET_ID Sheet1!C10 \
  --values-json '[["=SUM(Project_Tracker[Complete])"]]'

# List all tables
gog sheets table list SPREADSHEET_ID

Implementation Details

Smart Range Parsing: parseA1ToGridRangeWithLookup() resolves sheet names (e.g., "SalesData") to actual sheet IDs using spreadsheet metadata. This ensures tables are created on the correct sheet, not just Sheet1.

Footer Formula Preservation: Before append, captures footer cell formulas. After append, detects table expansion by comparing ranges. If expanded, re-applies formulas to the new footer row location using Values.Update.

Sheet Location Fix: Changed from AppendCellsRequest (which ignored table sheet location) to Values.Append with explicit sheet name in range (SheetName!Col:Col), ensuring data appends to the correct sheet.

Commits

1. feat(sheets): add table manipulation commands — initial implementation (7 commands, 871 lines)
2. fix(sheets): correct table append for multiple rows — fixed row flattening bug
3. fix(sheets): correct table range formatting — use sheet names in A1 notation
4. fix(sheets): footer update field mask — removed tableId from fields list
5. feat(sheets): smart range parsing + footer preservation — sheet ID lookup and formula preservation
6. fix(sheets): make append respect sheet location — fixed critical sheet routing bug

Files Changed

• internal/cmd/sheets_table.go — new file with all table commands (992 lines)
• internal/cmd/sheets.go — added Table SheetsTableCmd field

Testing

Comprehensive manual testing performed:

• ✅ Created tables on multiple sheets (Sheet1, TestSheet, SalesData)
• ✅ Verified smart range parsing resolves correct sheet IDs
• ✅ Tested table expansion when appending beyond capacity
• ✅ Verified footer formulas are preserved after expansion
• ✅ Tested all 7 commands (create, list, get, update, append, clear, delete)
• ✅ Tested column types: TEXT, DOUBLE, CURRENCY, DROPDOWN, DATE, PERCENT
• ✅ Verified data goes to correct sheet (fixed routing bug)

Checklist

• Code follows project patterns (Kong CLI, error handling, output formatting)
• All builds pass (make build)
• Manual testing completed
• Commits follow conventional commits format
• No breaking changes to existing functionality