fix(build): rename HttpMethod::DELETE to DEL for Windows compat

Windows headers define DELETE as a macro, causing MSVC build failures.
Also update development docs with repo layout, testing guide, and CI
pipeline overview. Add CLAUDE.md for quick reference.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: Michael Harris

CLAUDE.md

@@ -0,0 +1,18 @@
+# CLAUDE.md
+
+DuckDB extension for reading and writing Google Sheets.
+
+## Quick Reference
+
+- **Build:** `GEN=ninja make`
+- **Unit tests:** `make test_unit`
+- **SQL tests:** `TOKEN=your-token make test` or `./scripts/test_sql.sh path/to/keyfile.json`
+- **Format:** `make format`
+
+## Architecture
+
+The extension has three layers: **Transport** (HTTP client abstraction), **Auth** (bearer token, OAuth, service account), and **Service** (Google Sheets API client with spreadsheet/values resources). See `src/include/sheets/` for the interfaces.
+
+## Contributing
+
+See [docs/pages/development.md](docs/pages/development.md) for build setup, testing, repo layout, and CI pipeline details.

docs/pages/development.md

@@ -1,46 +1,118 @@
 # Development
 
+## Repository Layout
+
+```
+duckdb_gsheets/
+├── src/                        # Extension source code
+│   ├── include/                # Headers
+│   │   ├── sheets/             # Google Sheets client library
+│   │   │   ├── auth/           # Auth providers (bearer, OAuth, service account)
+│   │   │   ├── resources/      # API resources (spreadsheets, values)
+│   │   │   ├── transport/      # HTTP client abstraction
+│   │   │   └── util/           # Encoding, range parsing
+│   │   └── utils/              # Extension utilities (secrets, version)
+│   ├── sheets/                 # Client library implementation
+│   └── *.cpp                   # Extension entry points (read, copy, auth)
+├── test/
+│   ├── sql/                    # SQL logic tests (integration, requires credentials)
+│   └── unit/                   # C++ unit tests (standalone, no credentials needed)
+├── scripts/                    # Dev scripts (test runners, token generation)
+├── docs/                       # Documentation site
+├── .github/workflows/          # CI pipelines
+├── duckdb/                     # DuckDB submodule
+└── extension-ci-tools/         # DuckDB CI tooling submodule
+```
+
 ## Building
+
 ### Managing dependencies
-DuckDB extensions uses VCPKG for dependency management. Enabling VCPKG is very simple: follow the [installation instructions](https://vcpkg.io/en/getting-started) or just run the following:
+
+DuckDB extensions use VCPKG for dependency management. Follow the [installation instructions](https://vcpkg.io/en/getting-started) or run:
+
 ```shell
 git clone https://github.com/Microsoft/vcpkg.git
 ./vcpkg/bootstrap-vcpkg.sh
 export VCPKG_TOOLCHAIN_PATH=`pwd`/vcpkg/scripts/buildsystems/vcpkg.cmake
 ```
-Note: VCPKG is only required for extensions that want to rely on it for dependency management. If you want to develop an extension without dependencies, or want to do your own dependency management, just skip this step. Note that the example extension uses VCPKG to build with a dependency for instructive purposes, so when skipping this step the build may not work without removing the dependency.
 
 ### Build steps
-Now to build the extension, run:
+
+To build the extension:
+
 ```sh
 GEN=ninja make
 ```
+
 The main binaries that will be built are:
+
+- `./build/release/duckdb` — DuckDB shell with the extension auto-loaded
+- `./build/release/test/unittest` — SQL test runner with the extension linked in
+- `./build/release/extension/gsheets/gsheets.duckdb_extension` — loadable extension binary
+
+## Running the extension
+
+Start the shell with `./build/release/duckdb` and use the extension features directly.
+
+## Testing
+
+### Unit tests
+
+Unit tests are standalone C++ tests that use a mock HTTP client — no credentials or network access needed:
+
 ```sh
-./build/release/duckdb
-./build/release/test/unittest
-./build/release/extension/gsheets/gsheets.duckdb_extension
+make test_unit
 ```
-- `duckdb` is the binary for the duckdb shell with the extension code automatically loaded.
-- `unittest` is the test runner of duckdb. Again, the extension is already linked into the binary.
-- `gsheets.duckdb_extension` is the loadable binary as it would be distributed.
 
-## Running the extension
-To run the extension code, simply start the shell with `./build/release/duckdb`.
+### SQL tests
 
-Now we can use the features from the extension directly in DuckDB.
+SQL tests run against the real Google Sheets API and require credentials. There are two ways to run them:
 
-## Running the tests\
-To run the test suite, you need to generate a token for the Google Sheets API, follow the instructions in the README file to get one.
+**Option 1: With an access token**
+
+If you already have a Google Sheets API access token:
 
-Different tests can be created for DuckDB extensions. The primary way of testing DuckDB extensions should be the SQL tests in `./test/sql`. These SQL tests can be run using:
 ```sh
-TOKEN=your-token-here GEN=ninja make test
+TOKEN=your-token-here make test
+```
+
+**Option 2: With a service account key file**
+
+If you have a service account JSON key file, the test script will generate a token and set up both `TOKEN` and `KEY_FILE_PATH` for you:
+
+```sh
+./scripts/test_sql.sh path/to/keyfile.json
+```
+
+This script will:
+1. Set up a Python venv and install dependencies
+2. Generate an access token from the key file
+3. Set `TOKEN` and `KEY_FILE_PATH` environment variables
+4. Run `make test` (builds DuckDB + extension, then runs SQL logic tests)
+
+To obtain a key file, create a Google Cloud service account with access to the test spreadsheets and download its JSON key. See [Google's documentation](https://cloud.google.com/iam/docs/keys-create-delete) for details.
+
+## CI Pipeline
+
+The CI pipeline gates builds behind tests:
+
+```mermaid
+graph LR
+    A[push / pull_request] --> B[Unit Tests]
+    B --> C[SQL Tests]
+    C --> D[Build next]
+    C --> E[Build stable]
 ```
 
-### Installing the deployed binaries
-To install your extension binaries from S3, you will need to do two things. Firstly, DuckDB should be launched with the
-`allow_unsigned_extensions` option set to true. How to set this will depend on the client you're using. Some examples:
+- **Unit tests** — always run, no credentials needed
+- **SQL tests** — require `GSHEETS_KEY_FILE_JSON` repo secret; skip gracefully on fork PRs without credentials
+- **Distribution builds** — only start after both test stages pass
+
+For fork PRs, maintainers can manually trigger SQL tests via **Actions → SQL Tests → Run workflow**.
+
+## Installing deployed binaries
+
+DuckDB must be launched with `allow_unsigned_extensions` set to true:
 
 CLI:
 ```shell
@@ -57,15 +129,14 @@ NodeJS:
 db = new duckdb.Database(':memory:', {"allow_unsigned_extensions": "true"});
 ```
 
-Secondly, you will need to set the repository endpoint in DuckDB to the HTTP url of your bucket + version of the extension
-you want to install. To do this run the following SQL query in DuckDB:
+Set the repository endpoint to your bucket:
+
 ```sql
 SET custom_extension_repository='bucket.s3.eu-west-1.amazonaws.com/<your_extension_name>/latest';
 ```
-Note that the `/latest` path will allow you to install the latest extension version available for your current version of
-DuckDB. To specify a specific version, you can pass the version instead.
 
-After running these steps, you can install and load your extension using the regular INSTALL/LOAD commands in DuckDB:
+Then install and load:
+
 ```sql
 INSTALL gsheets
 LOAD gsheets
@@ -88,4 +159,4 @@ $ cmake-format --version
 
 ```sh
 make format
-```
+```

src/include/sheets/transport/http_type.hpp

@@ -6,7 +6,7 @@
 namespace duckdb {
 namespace sheets {
 
-enum class HttpMethod { GET, POST, PUT, DELETE };
+enum class HttpMethod { GET, POST, PUT, DEL };
 
 using HttpHeaders = std::map<std::string, std::string>;
 

src/sheets/transport/http_client.cpp

@@ -26,7 +26,7 @@ HttpResponse IHttpClient::Put(const std::string &url, const HttpHeaders &headers
 }
 
 HttpResponse IHttpClient::Delete(const std::string &url, const HttpHeaders &headers) {
-	return Execute(BuildRequest(HttpMethod::DELETE, url, headers));
+	return Execute(BuildRequest(HttpMethod::DEL, url, headers));
 }
 } // namespace sheets
 } // namespace duckdb

src/sheets/transport/httplib_client.cpp

@@ -57,7 +57,7 @@ HttpResponse HttpLibClient::Execute(const HttpRequest &request) {
 	case HttpMethod::PUT:
 		result = client.Put(path, headers, request.body, contentType);
 		break;
-	case HttpMethod::DELETE:
+	case HttpMethod::DEL:
 		result = client.Delete(path, headers);
 		break;
 	}