@coldge.com/gitbase 1.0.2 → 1.0.3

package/README.md

@@ -7,11 +7,13 @@ GitBase is a professional version control system for Supabase. It synchronizes y
 ## 🚀 Key Features
 
 - **Reverse Git Workflow**: Treats the Live Database as the Source of Truth.
+- **Smart Data Preservation**: Generates non-destructive `ALTER TABLE` operations instead of DROP/CREATE during pushes. 
+- **True 3-Way Merge**: Identifies common ancestors and auto-merges branch changes with conflict markers.
+- **Native Supabase Branching**: Deep integration with Supabase Pro Branches and generic multi-project environments.
+- **Dry-Run Safety**: Verify your local SQL syntax against the live database instantly via aborted transactions.
+- **Automated Snapshots**: Background daemon that automatically pulls and commits Dashboard UI changes.
 - **Dependency-Aware Restoration**: Automatically orders SQL execution (e.g., Tables before Views) using a DAG engine.
-- **Multi-Profile Branches**: Manage Production, Staging, and Development references using Git-like branches.
-- **Smart Change Detection**: Canonicalizes SQL to eliminate "noise" from formatting or whitespace.
-- **Remote History Backups**: Store and sync your history repository in Supabase Storage buckets.
-- **Production Guard**: RBAC protection for high-risk operations on protected branches.
+- **Production Guard**: RBAC protection for high-risk operations on protected branches, requiring Owner/Admin capabilities.
 
 ---
 
@@ -71,10 +73,12 @@ If someone breaks production, you can reset the database to a known good state i
 #### `login`
 Authenticate with the Supabase Management API.
 - **Usage**: `gitb login`
+- **Arguments**: None.
 
 #### `whoami`
 Displays the current logged-in user and organization access.
 - **Usage**: `gitb whoami`
+- **Arguments**: None.
 
 ### Project Configuration
 #### `init`
@@ -89,23 +93,39 @@ Initializes a `.gitbase` repository and links a project.
 #### `status`
 Summarizes differences between the live database and local `.sql` files.
 - **Usage**: `gitb status`
+- **Arguments**: None.
 
 #### `pull` | `add`
 Fetches schema definitions from the database to your local `supabase/` directory.
-- **Usage**: `gitb pull [files..]`
+- **Usage**: `gitb pull [files..] [options]`
 - **Arguments**:
   | Argument | Description |
   | :--- | :--- |
   | `files` | Optional. Specific files or directories to pull (defaults to all). |
+  | `--auto-commit` | Automatically create a commit snapshot after pulling. |
+  | `--message`, `-m` | Optional message for auto-commit. |
+
+#### `snapshot`
+Runs a background daemon that periodically checks for live database changes and auto-commits them.
+- **Usage**: `gitb snapshot [options]`
+- **Arguments**:
+  | Flag | Description |
+  | :--- | :--- |
+  | `--interval` | The interval in minutes to check for changes (default: 60). |
 
 #### `push`
-Applies local `.sql` files to the live database.
+Applies local `.sql` files to the live database using a single atomic transaction.
 - **Usage**: `gitb push [files..]`
 - **Arguments**:
   | Argument | Description |
   | :--- | :--- |
   | `files` | Optional. Specific files to push. |
 
+#### `verify`
+Safely tests your local `.sql` files against the remote database for syntax errors using an aborted transaction.
+- **Usage**: `gitb verify`
+- **Arguments**: None.
+
 ### Versioning & Comparison
 #### `commit`
 Saves a snapshot of the current local schema to the history.
@@ -117,15 +137,25 @@ Saves a snapshot of the current local schema to the history.
 
 #### `log`
 Displays a chronological list of commits for the current branch.
-- **Usage**: `gitb log`
+- **Usage**: `gitb log [file] [options]`
+- **Arguments**:
+  | Argument / Flag | Alias | Description |
+  | :--- | :--- | :--- |
+  | `file` | | Optional. Filter commits to only those that modified this specific file (e.g. `tables/users.sql`). |
+  | `--oneline` | | Compact one-line format. |
+  | `--since` | | Only show commits after this date (ISO format, e.g. `2026-01-01`). |
+  | `--max-count` | `-n` | Limit the output to the last N commits. |
 
 #### `diff`
 Shows a line-by-line comparison of SQL definitions.
-- **Usage**: `gitb diff [commit]`
+- **Usage**: `gitb diff [commit1] [commit2] [options]`
 - **Arguments**:
-  | Argument | Description |
+  | Argument / Flag | Description |
   | :--- | :--- |
-  | `commit` | Optional. The commit hash to compare against the Live DB (defaults to local HEAD). |
+  | `commit` | Compare a specific commit (or `HEAD~N`) against local files. |
+  | `commit1 commit2` | Compare two commits against each other. |
+  | `--live` | Compare the given commit against the Live Database instead of local files. |
+  | `--files` | Filter the diff to specific file paths (e.g. `tables/users.sql`). |
 
 ### Restoration
 #### `revert` | `reset`
@@ -139,7 +169,7 @@ Hard-resets the live database and local files to a previous commit.
 
 ### Multi-Environment Profiles
 #### `branch`
-Manages project environmental profiles.
+Manages project environmental profiles. If Native Supabase Branching is available, prompts to automatically provision a connected branch.
 - **Usage**: `gitb branch [name] [options]`
 - **Arguments**:
   | Flag | Alias | Description |
@@ -148,18 +178,38 @@ Manages project environmental profiles.
   | `--delete` | `-d` | Deletes the specified branch profile. |
 
 #### `checkout`
-Switches the active environment profile.
+Switches the active environment profile and automatically swaps local SQL files to match the target branch's HEAD.
 - **Usage**: `gitb checkout <name>`
 
 #### `merge`
-Synchronizes configuration and history from another branch profile.
+Performs a true 3-way merge from another branch into your current branch, auto-resolving non-conflicting changes and inserting conflict markers.
 - **Usage**: `gitb merge <name>`
 
+#### `stash`
+Saves your uncommitted local schema changes into a temporary commit-like stashed object.
+- **Usage**: `gitb stash [subcommand] [options]`
+- **Subcommands**: 
+  - `push` / `save` (default)
+  - `pop` (apply and drop)
+  - `apply` (apply without dropping)
+  - `list` / `ls`
+  - `drop`
+  - `clear`
+- **Arguments**:
+  | Flag | Alias | Description |
+  | :--- | :--- | :--- |
+  | `--message` | `-m` | Optional message for the stash (used with `push`/`save`). |
+  | `--index` | `-n` | The index of the stash to apply or drop (default is 0). |
+
 ### Cloud Sync
 #### `remote`
 Manages history backups in Supabase Storage.
-- **Usage**: `gitb remote <subcommand>`
-- **Subcommands**: `add`, `list`, `push`, `pull`.
+- **Usage**: `gitb remote <subcommand> [args]`
+- **Subcommands**: 
+  - `add <name> <bucket>`: Link a remote Supabase storage bucket (e.g. `gitb remote add origin my-backups`).
+  - `list` / `ls`: Show configured remotes.
+  - `push <name>`: Backup your `.gitbase/objects` and `config` to the remote bucket.
+  - `pull <name>`: Restore your `.gitbase` history from the remote bucket.
 
 ---
 

package/dist/api/supabase.js

@@ -4,10 +4,34 @@ import fs from 'fs/promises';
 import path from 'path';
 import pg from 'pg';
 import chalk from 'chalk';
-const { Client } = pg;
+const { Client, Pool } = pg;
 const API_URL = 'https://api.supabase.com/v1';
 const GITBASE_DIR = '.gitbase';
 const CONFIG_FILE = path.join(GITBASE_DIR, 'config');
+// ---------------------------------------------------------------------------
+// Per-command connection pool
+// A short-lived pool is kept alive for the duration of a single CLI command
+// invocation, then torn down. This collapses 6+ DB connections for a typical
+// 'status' or 'push' into 1-3, giving 3-5x fewer TCP handshakes on
+// high-latency connections to Supabase.
+// ---------------------------------------------------------------------------
+const pools = new Map();
+/** Call at the start of a command to create a reusable pool for this project. */
+export async function createPool(projectRef) {
+    if (pools.has(projectRef))
+        return;
+    const connectionString = await getConnectionString(projectRef);
+    const pool = new Pool({ connectionString, ssl: { rejectUnauthorized: false }, max: 3 });
+    pools.set(projectRef, pool);
+}
+/** Drain and remove the pool for this project. Call at the end of each command. */
+export async function endPool(projectRef) {
+    const pool = pools.get(projectRef);
+    if (pool) {
+        await pool.end();
+        pools.delete(projectRef);
+    }
+}
 export async function getProjects() {
     const token = await getToken();
     if (!token)
@@ -17,6 +41,22 @@ export async function getProjects() {
     });
     return response.data;
 }
+export async function createSupabaseBranch(projectRef, branchName) {
+    const token = await getToken();
+    if (!token)
+        throw new Error('Not logged in.');
+    // Creating a branch returns the branch object (we need the project_ref it gets assigned)
+    const response = await axios.post(`${API_URL}/projects/${projectRef}/branches`, { branch_name: branchName }, { headers: { Authorization: `Bearer ${token}` } });
+    return response.data; // { id, name, project_ref, parent_project_ref, status ... }
+}
+export async function getSupabaseBranch(projectRef, branchName) {
+    const token = await getToken();
+    if (!token)
+        throw new Error('Not logged in.');
+    const response = await axios.get(`${API_URL}/projects/${projectRef}/branches`, { headers: { Authorization: `Bearer ${token}` } });
+    const branches = response.data;
+    return branches.find(b => b.name === branchName);
+}
 export async function getConfig() {
     try {
         const content = await fs.readFile(CONFIG_FILE, 'utf-8');
@@ -26,13 +66,18 @@ export async function getConfig() {
         return null;
     }
 }
-export async function runQuery(projectRef, sql) {
-    // 1. Get Connection String from Config
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolves the database connection string for a given project ref.
+ * Supports both the current multi-branch config and the legacy flat config.
+ */
+export async function getConnectionString(projectRef) {
     let connectionString = '';
     try {
         const config = await getConfig();
         if (config) {
-            // New format
             if (config.branches) {
                 for (const b of Object.values(config.branches)) {
                     const branch = b;
@@ -42,7 +87,6 @@ export async function runQuery(projectRef, sql) {
                     }
                 }
             }
-            // Old format compatibility
             else if (config.projectRef === projectRef) {
                 connectionString = config.connectionString;
                 if (!connectionString && config.dbPassword) {
@@ -55,16 +99,55 @@ export async function runQuery(projectRef, sql) {
     if (!connectionString) {
         throw new Error('Database connection string not found in config. Please re-run `gitb init --force`.');
     }
-    // 2. Connect
-    // Use connection pooling URL provided by user
-    const client = new Client({
-        connectionString,
-        ssl: { rejectUnauthorized: false }
-    });
+    return connectionString;
+}
+// ---------------------------------------------------------------------------
+// Query execution
+// ---------------------------------------------------------------------------
+/**
+ * Executes a single SQL statement against the given project's database.
+ * Accepts a plain SQL string or a { text, values } parameterized query object
+ * (the latter prevents SQL injection for dynamic queries).
+ */
+export async function runQuery(projectRef, sql, params = []) {
+    // Use pooled connection if available, otherwise create a one-shot client
+    const pool = pools.get(projectRef);
+    if (pool) {
+        let queryConfig;
+        if (typeof sql === 'object') {
+            queryConfig = sql;
+        }
+        else if (params.length > 0) {
+            queryConfig = { text: sql, values: params };
+        }
+        else {
+            queryConfig = sql;
+        }
+        try {
+            const res = await pool.query(queryConfig);
+            return res.rows;
+        }
+        catch (err) {
+            throw new Error(`Database Error: ${err.message}`);
+        }
+    }
+    // Fallback: one-shot client (for calls outside a command lifecycle)
+    const connectionString = await getConnectionString(projectRef);
+    const client = new Client({ connectionString, ssl: { rejectUnauthorized: false } });
     try {
         await client.connect();
-        const res = await client.query(sql);
-        return res.rows; // Array of objects
+        let queryConfig;
+        if (typeof sql === 'object') {
+            queryConfig = sql;
+        }
+        else if (params.length > 0) {
+            queryConfig = { text: sql, values: params };
+        }
+        else {
+            queryConfig = sql;
+        }
+        const res = await client.query(queryConfig);
+        return res.rows;
     }
     catch (err) {
         throw new Error(`Database Error: ${err.message}`);
@@ -73,10 +156,42 @@ export async function runQuery(projectRef, sql) {
         await client.end();
     }
 }
-// --- STORAGE API ---
+/**
+ * Executes an ordered list of SQL statements inside a single BEGIN/COMMIT
+ * transaction. On any error, the transaction is rolled back automatically
+ * and an error is thrown — leaving the database unchanged.
+ *
+ * Use this for all push and revert operations so the database is never left
+ * in a partially-applied state.
+ */
+export async function runTransaction(projectRef, statements) {
+    if (statements.length === 0)
+        return;
+    // For the transaction, always use a dedicated client to ensure BEGIN/COMMIT
+    // are on the same connection (pools don't guarantee this).
+    const connectionString = await getConnectionString(projectRef);
+    const client = new Client({ connectionString, ssl: { rejectUnauthorized: false } });
+    await client.connect();
+    try {
+        await client.query('BEGIN');
+        for (const stmt of statements) {
+            await client.query(stmt);
+        }
+        await client.query('COMMIT');
+    }
+    catch (err) {
+        await client.query('ROLLBACK');
+        throw new Error(`Transaction rolled back — database unchanged. Reason: ${err.message}`);
+    }
+    finally {
+        await client.end();
+    }
+}
+// ---------------------------------------------------------------------------
+// Supabase Storage API
+// ---------------------------------------------------------------------------
 export async function listObjects(projectRef, bucket, prefix = '') {
     const token = await getToken();
-    // Using Supabase Storage API directly
     const url = `https://${projectRef}.supabase.co/storage/v1/object/list/${bucket}`;
     const response = await axios.post(url, {
         prefix,
@@ -88,10 +203,9 @@ export async function listObjects(projectRef, bucket, prefix = '') {
     });
     return response.data;
 }
-export async function uploadObject(projectRef, bucket, path, content) {
+export async function uploadObject(projectRef, bucket, filePath, content) {
     const token = await getToken();
-    const url = `https://${projectRef}.supabase.co/storage/v1/object/${bucket}/${path}`;
-    // Upload history file content
+    const url = `https://${projectRef}.supabase.co/storage/v1/object/${bucket}/${filePath}`;
     await axios.post(url, content, {
         headers: {
             Authorization: `Bearer ${token}`,
@@ -100,9 +214,9 @@ export async function uploadObject(projectRef, bucket, path, content) {
         }
     });
 }
-export async function downloadObject(projectRef, bucket, path) {
+export async function downloadObject(projectRef, bucket, filePath) {
     const token = await getToken();
-    const url = `https://${projectRef}.supabase.co/storage/v1/object/${bucket}/${path}`;
+    const url = `https://${projectRef}.supabase.co/storage/v1/object/${bucket}/${filePath}`;
     const response = await axios.get(url, {
         headers: { Authorization: `Bearer ${token}` },
         responseType: 'text'
@@ -122,40 +236,33 @@ export async function ensureBucket(projectRef, bucket) {
         });
     }
     catch (e) {
-        if (e.response?.status !== 409) {
-            throw e;
-        }
+        if (e.response?.status !== 409)
+            throw e; // 409 = already exists, OK
     }
 }
-// --- RBAC / PERMISSIONS ---
+// ---------------------------------------------------------------------------
+// RBAC / Permissions
+// ---------------------------------------------------------------------------
 export async function isProductionAdmin(projectRef) {
     const token = await getToken();
     if (!token)
         throw new Error('Not logged in.');
     try {
-        // 1. Get the organization for this project
         const projects = await getProjects();
         const project = projects.find((p) => p.id === projectRef);
         if (!project)
             throw new Error(`Project ${projectRef} not found in your account.`);
         const orgId = project.organization_id;
-        // 2. Get the current user's profile to find their ID/Email
-        // Actually, the easiest way with Management API is to list organization members
-        // and find the one that matches our token's identity.
-        // However, the Management API token itself doesn't easily reveal "who am I" 
-        // without an extra call.
         const userResp = await axios.get(`${API_URL}/me`, {
             headers: { Authorization: `Bearer ${token}` }
         });
         const myEmail = userResp.data.email;
-        // 3. Get org members and check role
         const membersResp = await axios.get(`${API_URL}/organizations/${orgId}/members`, {
             headers: { Authorization: `Bearer ${token}` }
         });
         const me = membersResp.data.find((m) => m.email === myEmail);
         if (!me)
             return false;
-        // Only Owners and Administrators can touch production
         const allowedRoles = ['Owner', 'Administrator'];
         return allowedRoles.includes(me.roleName);
     }

package/dist/commands/branch.js

@@ -2,7 +2,7 @@ import fs from 'fs/promises';
 import path from 'path';
 import chalk from 'chalk';
 import readline from 'readline';
-import { getConfig } from '../api/supabase.js';
+import { getConfig, createSupabaseBranch, getSupabaseBranch } from '../api/supabase.js';
 const GITBASE_DIR = '.gitbase';
 const CONFIG_FILE = path.join(GITBASE_DIR, 'config');
 export async function branch(argv) {
@@ -48,18 +48,59 @@ export async function branch(argv) {
         console.error(chalk.red(`Branch '${branchName}' already exists.`));
         return;
     }
-    const rl = readline.createInterface({
-        input: process.stdin,
-        output: process.stdout
-    });
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     const ask = (q) => new Promise(r => rl.question(q, r));
     console.log(chalk.blue(`Creating new branch: ${branchName}`));
-    const ref = await ask('Project Ref: ');
-    const connString = await ask('Connection URI: ');
-    if (!ref || !connString) {
-        console.error(chalk.red('Project Ref and Connection URI are required.'));
-        rl.close();
-        return;
+    console.log(`How should this branch connect?`);
+    console.log(`  [1] Create new native Supabase Branch (requires Pro plan)`);
+    console.log(`  [2] Link to existing separate Supabase project (Free tier compatible)`);
+    const choice = await ask('\nChoice [1/2]: ');
+    let ref = '';
+    let connString = '';
+    if (choice === '1') {
+        const parentRef = config.branches[config.currentBranch]?.projectRef || config.projectRef;
+        if (!parentRef) {
+            console.error(chalk.red('Could not determine parent project ref.'));
+            rl.close();
+            return;
+        }
+        try {
+            console.log(chalk.blue(`\nChecking for existing native Supabase branch...`));
+            let branch = await getSupabaseBranch(parentRef, branchName);
+            if (branch) {
+                console.log(chalk.green(`Found existing native branch '${branchName}'. Linking to it...`));
+            }
+            else {
+                console.log(chalk.blue(`Creating native Supabase branch from ${parentRef}...`));
+                branch = await createSupabaseBranch(parentRef, branchName);
+            }
+            ref = branch.project_ref;
+            // The connection string for a branch follows the standard Supabase format
+            // using the new branch's project_ref. We need the DB password, which we
+            // can assume is the same as the parent project for branching purposes,
+            // or we must ask the user for it if it's newly provisioned.
+            // But actually, native branches share the parent's password by default.
+            const parentConn = config.branches[config.currentBranch]?.connectionString || config.connectionString;
+            const url = new URL(parentConn);
+            connString = `postgres://${url.username}:${url.password}@aws-0-${branch.region ?? 'us-east-1'}.pooler.supabase.com:6543/postgres`;
+            console.log(chalk.green(`✓ Branch configured natively (Ref: ${ref})`));
+        }
+        catch (e) {
+            console.error(chalk.red(`Failed to link/create native branch. Does the parent project have branching enabled on a Pro plan?`));
+            console.error(chalk.red(`Error: ${e.response?.data?.message || e.message}`));
+            rl.close();
+            return;
+        }
+    }
+    else {
+        console.log('');
+        ref = await ask('Project Ref: ');
+        connString = await ask('Connection URI: ');
+        if (!ref || !connString) {
+            console.error(chalk.red('Project Ref and Connection URI are required.'));
+            rl.close();
+            return;
+        }
     }
     const currentHead = await fs.readFile(path.join(GITBASE_DIR, 'HEAD'), 'utf-8').catch(() => null);
     config.branches = config.branches || {};
@@ -72,6 +113,10 @@ export async function branch(argv) {
     console.log(chalk.green(`Branch '${branchName}' created.`));
     rl.close();
 }
+/**
+ * Switches to a branch and automatically updates local supabase/ files
+ * to match the branch's HEAD commit — no manual `gitb reset` needed.
+ */
 export async function checkout(argv) {
     const config = await getConfig();
     if (!config) {
@@ -87,10 +132,37 @@ export async function checkout(argv) {
         console.error(chalk.red(`Branch '${branchName}' does not exist.`));
         return;
     }
-    // Switch to target branch profile
+    if (branchName === config.currentBranch) {
+        console.log(chalk.yellow(`Already on branch '${branchName}'.`));
+        return;
+    }
+    // Switch config
     config.currentBranch = branchName;
     await fs.writeFile(CONFIG_FILE, JSON.stringify(config, null, 2));
-    // Swapping local 'supabase/' folder to match branch HEAD is recommended but not implemented yet.
     console.log(chalk.green(`Switched to branch '${branchName}'`));
-    console.log(chalk.yellow('Note: Your local files are unchanged. Run `gitb reset` to sync files with this branch\'s HEAD.'));
+    // Auto-swap local supabase/ files to match the branch's HEAD commit
+    const branchHead = config.branches[branchName].head;
+    if (!branchHead) {
+        console.log(chalk.yellow('  Branch has no commits yet — local files unchanged.'));
+        return;
+    }
+    try {
+        const { readCommit, readTree, readObject } = await import('../storage/git.js');
+        const commit = await readCommit(branchHead);
+        const tree = await readTree(commit.tree);
+        // Wipe supabase/ and rewrite from the branch's commit tree
+        await fs.rm('supabase', { recursive: true, force: true });
+        for (const [relPath, hash] of Object.entries(tree)) {
+            const fullPath = path.join('supabase', relPath);
+            await fs.mkdir(path.dirname(fullPath), { recursive: true });
+            const content = await readObject(hash);
+            await fs.writeFile(fullPath, content, 'utf-8');
+        }
+        // Update HEAD pointer
+        await fs.writeFile(path.join(GITBASE_DIR, 'HEAD'), branchHead, 'utf-8');
+        console.log(chalk.cyan(`  Local files updated to match HEAD (${branchHead.substring(0, 7)}).`));
+    }
+    catch (e) {
+        console.error(chalk.red(`  Failed to update local files: ${e.message}`));
+    }
 }