@coldge.com/gitbase 1.0.2

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Coldge
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# GitBase
+
+GitBase is a professional version control system for Supabase. It synchronizes your Live Database state with local SQL files, providing a robust workflow for tracking schema changes, managing multi-tenant environments, and performing safe database restores.
+
+---
+
+## 🚀 Key Features
+
+- **Reverse Git Workflow**: Treats the Live Database as the Source of Truth.
+- **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.
+
+---
+
+## 🛠️ Installation & Setup
+
+### 1. Installation
+Install the CLI globally via npm:
+```bash
+npm install -g @coldge.com/gitbase
+```
+
+### 2. Authentication
+Log in to your Supabase account using a Personal Access Token (PAT):
+```bash
+gitb login
+```
+*You can verify your status at any time with `gitb whoami`.*
+
+### 3. Initialization
+Link your current directory to a Supabase project:
+```bash
+gitb init
+```
+*Use `--force` if you need to re-initialize an existing directory.*
+
+---
+
+## 🔄 Core User Flow
+
+GitBase follows a simple, powerful cycle to keep your local and remote states in sync.
+
+### Phase 1: Tracking Changes (Live -> Local)
+When you modify a Table, Function, or Policy in the Supabase Dashboard, GitBase helps you bring those changes into your version control.
+
+1.  **Check Status**: `gitb status` identifies differences between your Live DB and local files.
+2.  **Pull Changes**: `gitb pull` (or `gitb add .`) downloads the latest SQL from Supabase.
+3.  **Snapshot**: `gitb commit -m "Describe your changes"` saves the state to your local history.
+
+### Phase 2: Deployment (Local -> Live)
+After merging a branch or making local adjustments, deploy them back to the database.
+
+1.  **Review**: `gitb diff` allows you to see what will change compared to the Live DB.
+2.  **Push**: `gitb push` applies your local SQL files to the database.
+3.  **Backup**: GitBase will automatically ask if you want to rename existing tables as backups before overwriting.
+
+### Phase 3: Disaster Recovery
+If someone breaks production, you can reset the database to a known good state instantly.
+
+1.  **Check Logs**: `gitb log` find the stable commit hash.
+2.  **Restore**: `gitb revert <hash>` restores the entire schema and logic to that exact point in time.
+
+---
+
+## 📖 Command Reference
+
+### Authentication
+#### `login`
+Authenticate with the Supabase Management API.
+- **Usage**: `gitb login`
+
+#### `whoami`
+Displays the current logged-in user and organization access.
+- **Usage**: `gitb whoami`
+
+### Project Configuration
+#### `init`
+Initializes a `.gitbase` repository and links a project.
+- **Usage**: `gitb init [options]`
+- **Arguments**:
+  | Flag | Alias | Description |
+  | :--- | :--- | :--- |
+  | `--force` | `-f` | Overwrite existing configuration. |
+
+### Synchronization
+#### `status`
+Summarizes differences between the live database and local `.sql` files.
+- **Usage**: `gitb status`
+
+#### `pull` | `add`
+Fetches schema definitions from the database to your local `supabase/` directory.
+- **Usage**: `gitb pull [files..]`
+- **Arguments**:
+  | Argument | Description |
+  | :--- | :--- |
+  | `files` | Optional. Specific files or directories to pull (defaults to all). |
+
+#### `push`
+Applies local `.sql` files to the live database.
+- **Usage**: `gitb push [files..]`
+- **Arguments**:
+  | Argument | Description |
+  | :--- | :--- |
+  | `files` | Optional. Specific files to push. |
+
+### Versioning & Comparison
+#### `commit`
+Saves a snapshot of the current local schema to the history.
+- **Usage**: `gitb commit -m <message>`
+- **Arguments**:
+  | Flag | Alias | Description |
+  | :--- | :--- | :--- |
+  | `--message` | `-m` | **Required.** The description of the snapshot. |
+
+#### `log`
+Displays a chronological list of commits for the current branch.
+- **Usage**: `gitb log`
+
+#### `diff`
+Shows a line-by-line comparison of SQL definitions.
+- **Usage**: `gitb diff [commit]`
+- **Arguments**:
+  | Argument | Description |
+  | :--- | :--- |
+  | `commit` | Optional. The commit hash to compare against the Live DB (defaults to local HEAD). |
+
+### Restoration
+#### `revert` | `reset`
+Hard-resets the live database and local files to a previous commit.
+- **Usage**: `gitb revert [commit] [options]`
+- **Arguments**:
+  | Argument | Description |
+  | :--- | :--- |
+  | `commit` | Optional. Hash of the target commit (defaults to HEAD). |
+  | `--files` | Optional. Restricts the revert to specific file paths. |
+
+### Multi-Environment Profiles
+#### `branch`
+Manages project environmental profiles.
+- **Usage**: `gitb branch [name] [options]`
+- **Arguments**:
+  | Flag | Alias | Description |
+  | :--- | :--- | :--- |
+  | `name` | | Positional. Name of the branch to create/list. |
+  | `--delete` | `-d` | Deletes the specified branch profile. |
+
+#### `checkout`
+Switches the active environment profile.
+- **Usage**: `gitb checkout <name>`
+
+#### `merge`
+Synchronizes configuration and history from another branch profile.
+- **Usage**: `gitb merge <name>`
+
+### Cloud Sync
+#### `remote`
+Manages history backups in Supabase Storage.
+- **Usage**: `gitb remote <subcommand>`
+- **Subcommands**: `add`, `list`, `push`, `pull`.
+
+---
+
+## 🛡️ Security & Safety
+
+> [!CAUTION]
+> **Token Security**: Your Management API token is stored in `~/.config/gitbase/token.json`. Ensure this file is never shared or accidentally committed to public repositories.
+
+> [!IMPORTANT]
+> **Protected Branches**: By default, any branch named `production` requires **Owner** or **Administrator** organizational permissions to execute `push` or `revert`. This prevents unauthorized destructive changes to live environments.
+
+---
+
+## ⚖️ License
+
+ISC License • Copyright (c) 2026 Coldge

package/dist/api/supabase.js

@@ -0,0 +1,166 @@
+import axios from 'axios';
+import { getToken } from '../utils/config.js';
+import fs from 'fs/promises';
+import path from 'path';
+import pg from 'pg';
+import chalk from 'chalk';
+const { Client } = pg;
+const API_URL = 'https://api.supabase.com/v1';
+const GITBASE_DIR = '.gitbase';
+const CONFIG_FILE = path.join(GITBASE_DIR, 'config');
+export async function getProjects() {
+    const token = await getToken();
+    if (!token)
+        throw new Error('Not logged in. Run `gitb login` first.');
+    const response = await axios.get(`${API_URL}/projects`, {
+        headers: { Authorization: `Bearer ${token}` }
+    });
+    return response.data;
+}
+export async function getConfig() {
+    try {
+        const content = await fs.readFile(CONFIG_FILE, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+export async function runQuery(projectRef, sql) {
+    // 1. Get Connection String from Config
+    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;
+                    if (branch.projectRef === projectRef) {
+                        connectionString = branch.connectionString;
+                        break;
+                    }
+                }
+            }
+            // Old format compatibility
+            else if (config.projectRef === projectRef) {
+                connectionString = config.connectionString;
+                if (!connectionString && config.dbPassword) {
+                    connectionString = `postgres://postgres:${config.dbPassword}@db.${projectRef}.supabase.co:5432/postgres`;
+                }
+            }
+        }
+    }
+    catch { }
+    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 }
+    });
+    try {
+        await client.connect();
+        const res = await client.query(sql);
+        return res.rows; // Array of objects
+    }
+    catch (err) {
+        throw new Error(`Database Error: ${err.message}`);
+    }
+    finally {
+        await client.end();
+    }
+}
+// --- 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,
+        limit: 1000,
+        offset: 0,
+        sortBy: { column: 'name', order: 'asc' }
+    }, {
+        headers: { Authorization: `Bearer ${token}` }
+    });
+    return response.data;
+}
+export async function uploadObject(projectRef, bucket, path, content) {
+    const token = await getToken();
+    const url = `https://${projectRef}.supabase.co/storage/v1/object/${bucket}/${path}`;
+    // Upload history file content
+    await axios.post(url, content, {
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/octet-stream',
+            'x-upsert': 'true'
+        }
+    });
+}
+export async function downloadObject(projectRef, bucket, path) {
+    const token = await getToken();
+    const url = `https://${projectRef}.supabase.co/storage/v1/object/${bucket}/${path}`;
+    const response = await axios.get(url, {
+        headers: { Authorization: `Bearer ${token}` },
+        responseType: 'text'
+    });
+    return response.data;
+}
+export async function ensureBucket(projectRef, bucket) {
+    const token = await getToken();
+    const url = `https://${projectRef}.supabase.co/storage/v1/bucket`;
+    try {
+        await axios.post(url, {
+            id: bucket,
+            name: bucket,
+            public: false
+        }, {
+            headers: { Authorization: `Bearer ${token}` }
+        });
+    }
+    catch (e) {
+        if (e.response?.status !== 409) {
+            throw e;
+        }
+    }
+}
+// --- 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);
+    }
+    catch (e) {
+        console.error(chalk.red(`Permission Check Failed: ${e.message}`));
+        return false;
+    }
+}

package/dist/commands/add.js

@@ -0,0 +1,34 @@
+import fs from 'fs/promises';
+import path from 'path';
+import chalk from 'chalk';
+import { getStatus } from './status.js';
+export async function add(argv) {
+    const changes = await getStatus();
+    if (!changes)
+        return;
+    // For "." or empty files, process all changes
+    const files = argv.files || [];
+    const isAll = files.length === 0 || files.includes('.');
+    const toProcess = isAll ? changes : changes.filter((c) => files.includes(c.path));
+    if (toProcess.length === 0) {
+        console.log(chalk.yellow('No changes to add.'));
+        return;
+    }
+    for (const change of toProcess) {
+        const fullPath = path.join('supabase', change.path);
+        if (change.type === 'deleted') {
+            try {
+                await fs.unlink(fullPath);
+                console.log(chalk.red(`Deleted: ${change.path}`));
+            }
+            catch (e) {
+                // Ignore if already deleted
+            }
+        }
+        else {
+            await fs.mkdir(path.dirname(fullPath), { recursive: true });
+            await fs.writeFile(fullPath, change.content, 'utf-8');
+            console.log(chalk.green(`Updated: ${change.path}`));
+        }
+    }
+}

package/dist/commands/branch.js

@@ -0,0 +1,96 @@
+import fs from 'fs/promises';
+import path from 'path';
+import chalk from 'chalk';
+import readline from 'readline';
+import { getConfig } from '../api/supabase.js';
+const GITBASE_DIR = '.gitbase';
+const CONFIG_FILE = path.join(GITBASE_DIR, 'config');
+export async function branch(argv) {
+    const config = await getConfig();
+    if (!config) {
+        console.error(chalk.red('Not initialized. Run `gitb init` first.'));
+        return;
+    }
+    const branchName = argv.name;
+    const isDelete = argv.d || argv.delete;
+    if (!branchName) {
+        // List branches
+        console.log(chalk.cyan('Branches:'));
+        for (const name of Object.keys(config.branches || {})) {
+            if (name === config.currentBranch) {
+                console.log(chalk.green(`* ${name}`));
+            }
+            else {
+                console.log(`  ${name}`);
+            }
+        }
+        return;
+    }
+    if (isDelete) {
+        if (branchName === 'production') {
+            console.error(chalk.red('Cannot delete the protected "production" branch.'));
+            return;
+        }
+        if (branchName === config.currentBranch) {
+            console.error(chalk.red('Cannot delete the current branch. Switch to another branch first.'));
+            return;
+        }
+        if (!config.branches || !config.branches[branchName]) {
+            console.error(chalk.red(`Branch '${branchName}' does not exist.`));
+            return;
+        }
+        delete config.branches[branchName];
+        await fs.writeFile(CONFIG_FILE, JSON.stringify(config, null, 2));
+        console.log(chalk.red(`Deleted branch '${branchName}'.`));
+        return;
+    }
+    if (config.branches && config.branches[branchName]) {
+        console.error(chalk.red(`Branch '${branchName}' already exists.`));
+        return;
+    }
+    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;
+    }
+    const currentHead = await fs.readFile(path.join(GITBASE_DIR, 'HEAD'), 'utf-8').catch(() => null);
+    config.branches = config.branches || {};
+    config.branches[branchName] = {
+        projectRef: ref.trim(),
+        connectionString: connString.trim(),
+        head: currentHead
+    };
+    await fs.writeFile(CONFIG_FILE, JSON.stringify(config, null, 2));
+    console.log(chalk.green(`Branch '${branchName}' created.`));
+    rl.close();
+}
+export async function checkout(argv) {
+    const config = await getConfig();
+    if (!config) {
+        console.error(chalk.red('Not initialized. Run `gitb init` first.'));
+        return;
+    }
+    const branchName = argv.name;
+    if (!branchName) {
+        console.error(chalk.red('Branch name required.'));
+        return;
+    }
+    if (!config.branches || !config.branches[branchName]) {
+        console.error(chalk.red(`Branch '${branchName}' does not exist.`));
+        return;
+    }
+    // Switch to target branch profile
+    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.'));
+}

package/dist/commands/clone.js

@@ -0,0 +1,65 @@
+import fs from 'fs/promises';
+import path from 'path';
+import chalk from 'chalk';
+import readline from 'readline';
+import { downloadFromStorage, listStorageObjects } from '../api/supabase.js';
+const GITBASE_DIR = '.gitbase';
+const CONFIG_FILE = path.join(GITBASE_DIR, 'config');
+const OBJECTS_DIR = path.join(GITBASE_DIR, 'objects');
+const BUCKET_NAME = 'gitbase-remotes';
+export async function clone(argv) {
+    const projectRef = argv.ref;
+    if (!projectRef) {
+        console.error(chalk.red('Project Reference ID required.'));
+        return;
+    }
+    console.log(chalk.blue(`Cloning GitBase history from project '${projectRef}'...`));
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    const ask = (q) => new Promise(r => rl.question(q, r));
+    // 1. Setup local dir
+    try {
+        await fs.mkdir(GITBASE_DIR, { recursive: true });
+        await fs.mkdir(OBJECTS_DIR, { recursive: true });
+    }
+    catch (e) { }
+    // 2. Download Config from Bucket
+    let config;
+    try {
+        const configStr = await downloadFromStorage(projectRef, BUCKET_NAME, 'config.json');
+        config = JSON.parse(configStr);
+        await fs.writeFile(CONFIG_FILE, JSON.stringify(config, null, 2));
+    }
+    catch (e) {
+        console.error(chalk.red(`Failed to download project configuration from bucket: ${e.message}`));
+        console.log(chalk.yellow('Make sure the project has been initialized with `gitb init` and the bucket exists.'));
+        rl.close();
+        return;
+    }
+    // 3. Download All Objects
+    console.log(chalk.blue('Downloading commit history...'));
+    try {
+        const objects = await listStorageObjects(projectRef, BUCKET_NAME, 'objects/');
+        for (const obj of objects) {
+            const hash = obj.name;
+            const content = await downloadFromStorage(projectRef, BUCKET_NAME, `objects/${hash}`);
+            await fs.writeFile(path.join(OBJECTS_DIR, hash), content, 'utf-8');
+        }
+    }
+    catch (e) {
+        console.warn(chalk.yellow('Failed to download some history objects.'));
+    }
+    // 4. Update HEAD to match branch head
+    if (config.branches && config.branches[config.currentBranch]) {
+        const head = config.branches[config.currentBranch].head;
+        if (head) {
+            await fs.writeFile(path.join(GITBASE_DIR, 'HEAD'), head);
+        }
+    }
+    console.log(chalk.green(`\nSuccessfully cloned project '${projectRef}'.`));
+    console.log(chalk.yellow(`Current branch: ${config.currentBranch}`));
+    console.log(chalk.blue('Run `gitb reset` to sync your local files with the database.'));
+    rl.close();
+}

package/dist/commands/commit.js

@@ -0,0 +1,99 @@
+import fs from 'fs/promises';
+import path from 'path';
+import chalk from 'chalk';
+import { hashString } from '../utils/hashing.js';
+const GITBASE_DIR = '.gitbase';
+const OBJECTS_DIR = path.join(GITBASE_DIR, 'objects');
+const HEAD_FILE = path.join(GITBASE_DIR, 'HEAD');
+export async function commit(argv) {
+    const message = argv.message;
+    if (!message) {
+        console.error(chalk.red('Commit message required.'));
+        return;
+    }
+    // 1. Build Tree
+    const tree = {};
+    const supabaseDir = 'supabase';
+    // Recursive file walker
+    async function walk(dir, base) {
+        const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            const relPath = path.join(base, entry.name).replace(/\\/g, '/'); // normalize path
+            if (entry.isDirectory()) {
+                await walk(fullPath, relPath);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.sql')) {
+                const content = await fs.readFile(fullPath, 'utf-8');
+                const hash = hashString(content);
+                await saveObject(hash, content);
+                tree[relPath] = hash;
+            }
+        }
+    }
+    // Check if supabase dir exists
+    try {
+        await fs.access(supabaseDir);
+        await walk(supabaseDir, '');
+    }
+    catch {
+        console.log(chalk.yellow('Nothing to commit (supabase directory missing).'));
+        return;
+    }
+    if (Object.keys(tree).length === 0) {
+        console.log(chalk.yellow('Nothing to commit (empty working tree).'));
+        return;
+    }
+    // Save Tree Object
+    const sortedTree = Object.keys(tree).sort().reduce((acc, key) => {
+        acc[key] = tree[key];
+        return acc;
+    }, {});
+    const treeJson = JSON.stringify(sortedTree);
+    const treeHash = hashString(treeJson);
+    await saveObject(treeHash, treeJson);
+    // 2. Get Parent
+    let parent = null;
+    let parentTreeHash = null;
+    try {
+        parent = await fs.readFile(HEAD_FILE, 'utf-8');
+        if (parent) {
+            const parentCommitStr = await fs.readFile(path.join(OBJECTS_DIR, parent), 'utf-8');
+            const parentCommit = JSON.parse(parentCommitStr);
+            parentTreeHash = parentCommit.tree;
+        }
+    }
+    catch { }
+    // Prevent empty commits
+    if (parentTreeHash === treeHash) {
+        console.log(chalk.yellow('Nothing to commit (working tree clean).'));
+        return;
+    }
+    // 3. Create Commit Object
+    const commitObj = {
+        tree: treeHash,
+        parent: parent,
+        message: message,
+        timestamp: new Date().toISOString(),
+        author: process.env.USERNAME || process.env.USER || 'unknown'
+    };
+    const commitJson = JSON.stringify(commitObj, null, 2);
+    const commitHash = hashString(commitJson);
+    await saveObject(commitHash, commitJson);
+    // 4. Update HEAD
+    await fs.writeFile(HEAD_FILE, commitHash, 'utf-8');
+    // 5. Update branch HEAD in config
+    const { getConfig } = await import('../api/supabase.js');
+    const config = await getConfig();
+    if (config && config.branches && config.currentBranch) {
+        config.branches[config.currentBranch].head = commitHash;
+        await fs.writeFile(path.join(GITBASE_DIR, 'config'), JSON.stringify(config, null, 2));
+    }
+    console.log(chalk.green(`[${commitHash.substring(0, 7)}] ${message}`));
+}
+async function saveObject(hash, content) {
+    await fs.mkdir(OBJECTS_DIR, { recursive: true });
+    // Maybe use subdirectories like git (ab/cdef...) to avoid too many files in one dir
+    // For MVP, flat is fine.
+    await fs.writeFile(path.join(OBJECTS_DIR, hash), content, 'utf-8');
+}