feat: Add external spreadsheet support with read-only access

[Copilot]

This PR implements external spreadsheet support for the GASS framework, allowing read-only access to external Google Sheets using the Sheets API. The implementation enables developers to create Entry classes that retrieve data from spreadsheets outside of the current active spreadsheet while maintaining the same familiar API.

Key Features

External Entry Definition: Extended IEntryMeta interface with an optional spreadsheetId field. When present, the entry is treated as external and uses the sheet name (string) instead of numeric sheet ID:

export class Affiliate extends Entry {
  static override _meta: IEntryMeta = {
    spreadsheetId: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    sheetId: "Affiliates", // Sheet name for external sheets
    headerRow: 1,
    dataStartColumn: 1,
    dataEndColumn: 5,
    columns: ["name", "representative", "address", "website", "notes"],
    defaultSort: [{ column: "name", ascending: true }],
  };
}

Optimized Filtering: Implements the exact scenario described in the issue using efficient API calls:

// This filtering operation:
Affiliate.get({ representative: "Kevin Shenk" })

// Generates optimal API calls:
// 1. Sheets.Spreadsheets.Values.batchGet to filter by representative column
// 2. Sheets.Spreadsheets.Values.get for complete matching rows

Read-Only Protection: External entries are automatically protected from modification operations. Attempts to save, update, or delete external entries throw clear error messages, preventing accidental data corruption.

A1 Notation Generation: Automatically synthesizes proper A1 notation from sheet metadata, converting column numbers to letters (1→A, 27→AA) and generating ranges like "Affiliates!B2:B" for filtering operations.

Technical Implementation

• Backward Compatibility: All existing internal sheet entries continue to work unchanged
• Mixed Registration: EntryRegistry supports both internal and external entries in the same application
• Type Safety: Full TypeScript support with proper type constraints and error handling
• Performance: Uses batchGet for filtering to minimize API calls and data transfer

API Coverage

The implementation supports all standard Entry methods for external sheets:

• Entry.get(filters) - Filtered retrieval with external optimization
• Entry.getAll() - Bulk retrieval from external sheets
• Entry.getValue(filters, column) - Single value extraction
• Write operations (save, delete, batchSave) are properly blocked with informative errors

Documentation

Includes comprehensive documentation with working examples, API explanations, best practices, and unit tests to validate core functionality.

Fixes #1.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

@batonac 👋 This repository doesn't have Copilot instructions. With Copilot instructions, I can understand the repository better, work faster and produce higher quality PRs.

I can generate a .github/copilot-instructions.md file for you automatically. Click here to open a pre-filled issue and assign it to me. I'll write the instructions, and then tag you for review.