GS: Google Sheets integration project

Inizia con il catalogo di progettazione in docs/design/google-sheets/README.md e rivedi #397 prima dell’implementazione. Segui la sequenza delle dipendenze da #399 a #405, iniziando con OAuth, Picker e l’esportazione degli snapshot. Il lavoro è completato quando i criteri di accettazione elencati sono soddisfatti, inclusi un refresh sicuro in caso di errore, una modalità append controllata dalle capabilities e aggiornamenti corrispondenti del catalogo.

Summary

Implement the browser-only Google Sheets integration defined by the repository design catalog introduced in #397.

Design entry point:

• https://github.com/Altinity/altinity-sql-browser/blob/docs/google-sheets-design/docs/design/google-sheets/README.md

Product scope

• One-time snapshot export.
• Create or attach a linked spreadsheet.
• Manual refresh through a hyperlink that launches the ClickHouse-hosted SPA.
• Failure-safe full refresh through staging.
• Large-result streaming and quota handling.
• Append-only refresh for validated ClickHouse 26.8+ MergeTree-family sources using per-partition _block_number / _block_offset checkpoints.
• Refresh history, repair, and unlink workflows.

Non-goals

• Scheduled/background refresh.
• Refresh while SQL Browser is closed.
• SELECT ... STREAM.
• Updates/deletes/upserts in append mode.
• Google Docs, Apps Script, service accounts, or an application backend.
• Strict distributed locking between collaborators.

Project acceptance criteria

• Existing behavior is unchanged when Google Sheets configuration is absent.
• Google and ClickHouse authorization remain independent and browser-only.
• Linked refresh preserves previous committed data on every pre-publication failure.
• No silent truncation or silent append-to-full fallback occurs.
• Managed resources are identified by stable IDs and metadata, not names.
• Append mode is capability-gated and invalidates safely.
• Design changes are updated in the catalog in the same PR as implementation changes.

Implementation sequence

• #399 — Google OAuth, Picker, and snapshot export
• #400 — Linked-sheet resource and ClickHouse binding storage
• #401 — Managed spreadsheet layout and manual refresh route
• #402 — Failure-safe full refresh and large-result transfer
• #403 — ClickHouse 26.8+ commit-cursor append refresh
• #404 — Refresh history, repair, and unlink workflows
• #405 — End-to-end Google Sheets integration test suite

Dependency outline

#399
  ↓
#400
  ↓
#401
  ↓
#402
  ├──→ #403
  └──→ #404
          ↓
        #405

Design baseline

#397 is documentation-only and should be reviewed before feature implementation begins.