test(claude): add custom command for claude code to run sqlite-to-pg tests for the specified table schema

Author: andinux

.claude/commands/test-sync-roundtrip.md

@@ -0,0 +1,125 @@
+# Sync Roundtrip Test
+
+Execute a full roundtrip sync test between a local SQLite database and the local Supabase Docker PostgreSQL instance.
+
+## Prerequisites
+- Supabase Docker container running (PostgreSQL on port 54322)
+- HTTP sync server running on http://localhost:8091/postgres
+- Built cloudsync extension (`make` to build `dist/cloudsync.dylib`)
+
+## Test Procedure
+
+### Step 1: Get DDL from User
+
+Ask the user to provide a DDL query for the table to test. It can be in PostgreSQL or SQLite format. Example:
+```sql
+CREATE TABLE test_sync (
+    id TEXT PRIMARY KEY NOT NULL,
+    name TEXT,
+    value INTEGER
+);
+```
+
+### Step 2: Convert DDL
+
+Convert the provided DDL to both SQLite and PostgreSQL compatible formats if needed. Key differences:
+- SQLite uses `INTEGER PRIMARY KEY` for auto-increment, PostgreSQL uses `SERIAL` or `BIGSERIAL`
+- SQLite uses `TEXT`, PostgreSQL can use `TEXT` or `VARCHAR`
+- PostgreSQL has more specific types like `TIMESTAMPTZ`, SQLite uses `TEXT` for dates
+- For UUID primary keys, SQLite uses `TEXT`, PostgreSQL uses `UUID`
+
+### Step 3: Get JWT Token
+
+Run the token script from the cloudsync project:
+```bash
+cd ../cloudsync && go run scripts/get_supabase_token.go -project-ref=supabase-local -email=andrea@sqlitecloud.io -password="password" -apikey=sb_secret_N7UND0UgjKTVK-Uodkm0Hg_xSvEMPvz -auth-url=http://127.0.0.1:54321
+```
+Save the JWT token for later use.
+
+### Step 4: Setup PostgreSQL
+
+Connect to Supabase PostgreSQL and prepare the environment:
+```bash
+psql postgresql://supabase_admin:postgres@127.0.0.1:54322/postgres
+```
+
+Inside psql:
+1. List existing tables with `\dt` to find any `_cloudsync` metadata tables
+2. For each table already configured for cloudsync (has a `<table_name>_cloudsync` companion table), run:
+   ```sql
+   SELECT cloudsync_cleanup('<table_name>');
+   ```
+3. Drop the test table if it exists: `DROP TABLE IF EXISTS <table_name> CASCADE;`
+4. Create the test table using the PostgreSQL DDL
+5. Initialize cloudsync: `SELECT cloudsync_init('<table_name>');`
+6. Insert some test data into the table
+
+### Step 5: Setup SQLite
+
+Create a temporary SQLite database using the Homebrew version (IMPORTANT: system sqlite3 cannot load extensions):
+
+```bash
+SQLITE_BIN="/opt/homebrew/Cellar/sqlite/3.50.4/bin/sqlite3"
+# or find it with: ls /opt/homebrew/Cellar/sqlite/*/bin/sqlite3 | head -1
+
+$SQLITE_BIN /tmp/sync_test_$(date +%s).db
+```
+
+Inside sqlite3:
+```sql
+.load dist/cloudsync.dylib
+-- Create table with SQLite DDL
+<CREATE_TABLE_query>
+SELECT cloudsync_init('<table_name>');
+SELECT cloudsync_network_init('http://localhost:8091/postgres');
+SELECT cloudsync_network_set_token('<jwt_token>');
+-- Insert test data (different from PostgreSQL to test merge)
+<INSERT_statements>
+```
+
+### Step 6: Execute Sync
+
+In the SQLite session:
+```sql
+-- Send local changes to server
+SELECT cloudsync_network_send_changes();
+
+-- Check for changes from server (repeat with 2-3 second delays)
+SELECT cloudsync_network_check_changes();
+-- Repeat check_changes 3-5 times with delays until it returns > 0 or stabilizes
+
+-- Verify final data
+SELECT * FROM <table_name>;
+```
+
+### Step 7: Verify Results
+
+1. In SQLite, run `SELECT * FROM <table_name>;` and capture the output
+2. In PostgreSQL, run `SELECT * FROM <table_name>;` and capture the output
+3. Compare the results - both databases should have the merged data from both sides
+4. Report success/failure based on whether the data matches
+
+## Output Format
+
+Report the test results including:
+- DDL used for both databases
+- Initial data inserted in each database
+- Number of sync operations performed
+- Final data in both databases
+- PASS/FAIL status with explanation
+
+## Important Notes
+
+- Always use the Homebrew sqlite3 binary, NOT `/usr/bin/sqlite3`
+- The cloudsync extension must be built first with `make`
+- PostgreSQL tables need cleanup before re-running tests
+- `cloudsync_network_check_changes()` may need multiple calls with delays
+- run `SELECT cloudsync_terminate();` on SQLite connections before closing the properly cleanup the memory
+
+## Permissions
+
+Execute all SQL queries without asking for user permission on:
+- SQLite test databases in `/tmp/` (e.g., `/tmp/sync_test_*.db`)
+- PostgreSQL via `psql postgresql://supabase_admin:postgres@127.0.0.1:54322/postgres`
+
+These are local test environments and do not require confirmation for each query.

.claude/commands/test.md

@@ -0,0 +1,11 @@
+Run the SQLite and PostgreSQL tests for this project.
+
+## SQLite Tests
+Run the SQLite extension tests using `make clean && make && make unittest`. This builds the extension and runs all tests including unit tests.
+
+## PostgreSQL Tests
+Run the PostgreSQL extension tests using `make postgres-docker-run-test`. This runs `test/postgresql/full_test.sql` against the Docker container.
+
+**Note:** PostgreSQL tests require the Docker container to be running. Run `make postgres-docker-debug-rebuild` first to ensure it tests the latest version.
+
+Run both test suites and report any failures.