Instruction file imported from harrysayers7/cursor-rules (.cursor/rules/04-git-hooks-automation.mdc). Copyright stays with the author.

description: Semi-automatic Git hook setup for Supabase project tracking with fallback options globs: /.git/, /setup-git-hooks.sh, /.env.example alwaysApply: false

Git Hooks & Supabase Automation

Semi-Automatic Project Setup

When starting a new project, Cursor will offer to:

1. Detect if Git hooks are needed for Supabase tracking
2. Create the setup script with fallback mechanisms
3. Initialize Git repository if needed
4. Assist with environment variables (MCP when available, manual fallback)
5. Install and configure the post-commit hook

Important: This is an optional enhancement for teams using Cursor + Supabase. It prioritizes reliability and developer control over full automation.

Project Detection Rules

When to Set Up Git Hooks

• ✅ New project with .cursor/rules/ directory
• ✅ Existing project with Supabase integration mentioned
• ✅ Project with package.json or similar dependency files
• ✅ User explicitly asks for Git tracking

When NOT to Set Up

• ❌ Simple scripts or one-off files
• ❌ Documentation-only repositories
• ❌ Temporary or experimental projects

Semi-Automatic Setup Process

1. MCP Integration (When Available)

# Cursor attempts to use Supabase MCP tools
# Falls back to manual configuration if MCP unavailable
# MCP provides: project_id, anon_key, url (when working)

# Check MCP availability
if command -v cursor &> /dev/null && [ -n "$CURSOR_MCP_ENABLED" ]; then
  echo "✅ MCP integration available"
  # Attempt to get credentials via MCP
  SUPABASE_URL=$(cursor mcp get-supabase-url 2>/dev/null || echo "")
  SUPABASE_ANON_KEY=$(cursor mcp get-supabase-key 2>/dev/null || echo "")
else
  echo "⚠️  MCP not available, using manual configuration"
fi

2. Git Repository Check

# Initialize Git if needed
if [ ! -d ".git" ]; then
  git init
  echo "✅ Git repository initialized"
fi

3. Setup Script Creation (with Fallback)

# Create setup-git-hooks.sh if it doesn't exist
if [ ! -f "setup-git-hooks.sh" ]; then
  if [ -f "/path/to/cursor-rules/setup-git-hooks.sh" ]; then
    cp /path/to/cursor-rules/setup-git-hooks.sh .
    chmod +x setup-git-hooks.sh
    echo "✅ Git hook setup script created"
  else
    echo "⚠️  Template not found, manual setup required"
  fi
fi

4. Environment Configuration (with Fallbacks)

# MCP-Enhanced Environment (when available)
# Cursor attempts to get Supabase credentials via MCP
# Falls back to manual input if MCP fails

# Fallback to manual input if MCP failed
if [ -z "$SUPABASE_URL" ]; then
  echo "Please provide Supabase configuration:"
  read -p "Enter Supabase URL: " SUPABASE_URL
  read -p "Enter Supabase Anon Key: " SUPABASE_ANON_KEY
  read -p "Enter Project ID (optional): " PROJECT_ID
fi

# Validate required fields
if [ -z "$SUPABASE_URL" ] || [ -z "$SUPABASE_ANON_KEY" ]; then
  echo "❌ Error: Missing required Supabase configuration"
  exit 1
fi

Cursor Integration Commands

Natural Language Triggers

When you say any of these, Cursor will offer to set up Git hooks (with MCP when available):

• "Set up Git tracking for this project"
• "Add Supabase project tracking"
• "Track commits in Supabase"
• "Set up automated Git hooks"
• "Initialize project tracking"
• "Create a new Supabase project"

Detection & Fallback

Cursor will detect when to offer Git hook setup when:

• You create a new .cursor/rules/ directory
• You mention "Supabase" in project context
• You add database-related files
• You create a new project structure

Important: Always provides fallback to manual configuration if MCP is unavailable or fails.

Setup Script Template

The setup-git-hooks.sh script will be created with MCP integration and fallback mechanisms:

#!/bin/bash
# Git Hook Setup for Supabase Project Tracking
# Uses MCP when available, falls back to manual configuration

PROJECT_NAME="${1:-$(basename $(pwd))}"

# Function to check MCP availability
check_mcp() {
  if command -v cursor &> /dev/null && [ -n "$CURSOR_MCP_ENABLED" ]; then
    return 0
  else
    return 1
  fi
}

# MCP Integration (with fallbacks)
if check_mcp; then
  echo "✅ MCP integration available"
  # Attempt to get credentials via MCP
  SUPABASE_URL=$(cursor mcp get-supabase-url 2>/dev/null || echo "")
  SUPABASE_ANON_KEY=$(cursor mcp get-supabase-key 2>/dev/null || echo "")
  PROJECT_ID=$(cursor mcp get-project-id 2>/dev/null || echo "")
else
  echo "⚠️  MCP not available, using manual configuration"
fi

# Fallback to manual input if MCP failed
if [ -z "$SUPABASE_URL" ]; then
  echo "Please provide Supabase configuration:"
  read -p "Supabase URL: " SUPABASE_URL
  read -p "Supabase Anon Key: " SUPABASE_ANON_KEY
  read -p "Project ID (optional): " PROJECT_ID
fi

# Validate required fields
if [ -z "$SUPABASE_URL" ] || [ -z "$SUPABASE_ANON_KEY" ]; then
  echo "❌ Error: Missing required Supabase configuration"
  exit 1
fi

Environment Configuration

MCP-Enhanced Setup (When Available)

# Cursor + MCP attempts to handle:
# ✅ SUPABASE_ANON_KEY (from MCP configuration)
# ✅ SUPABASE_URL (from MCP configuration)
# ✅ PROJECT_ID (from MCP project creation)
# ✅ Authentication (via MCP tools)

# Falls back to manual configuration if MCP fails

Manual Configuration (Fallback)

# .env.local (required if MCP is unavailable)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key-here
PROJECT_ID=your-project-id
PROJECT_NAME=my-awesome-project
GIT_HOOK_ENABLED=true
MCP_ENABLED=false  # Disable MCP if causing issues

Project Integration

Cursor Rules Integration

Add to your project's .cursor/rules/00-project-context.mdc:

## Git Tracking
- **Enabled**: Automatic Git commit tracking to Supabase
- **Project ID**: [Your project name in Supabase]
- **Tracking**: Commits, operations, deployments
- **Dashboard**: Available in Supabase dashboard

Package.json Integration

Add to package.json:

{
  "scripts": {
    "setup-tracking": "./setup-git-hooks.sh",
    "track-commit": "git add . && git commit -m 'Tracked commit'",
    "view-dashboard": "open https://supabase.com/dashboard/project/zeopoimfsxdidkyiucsr"
  }
}

Important Limitations & Considerations

MCP Dependency

• Requires: Cursor with MCP integration enabled
• Fallback: Manual configuration always available
• Security: Credentials handled through MCP (review security implications)

Vendor Lock-in

• Supabase dependency: Creates coupling to Supabase
• Mitigation: Standard Git hooks and HTTP APIs used
• Export: Data can be exported from Supabase for migration

Complexity Trade-off

• Benefit: Streamlined setup when MCP works
• Cost: Added complexity vs. simple manual setup
• Control: Easy to disable or remove the system

Troubleshooting

Common Issues

1. Missing jq: brew install jq (macOS) or sudo apt-get install jq (Ubuntu)
2. Permission denied: chmod +x setup-git-hooks.sh
3. MCP not available: Use manual configuration mode
4. Supabase connection failed: Check credentials and network
5. Git not initialized: Run git init first

Debug Commands

# Test the hook manually
.git/hooks/post-commit

# Check MCP availability
cursor mcp status 2>/dev/null || echo "MCP not available"

# Test Supabase connection
curl -H "apikey: $SUPABASE_ANON_KEY" \
  "$SUPABASE_URL/rest/v1/projects"

# Check environment variables
echo "SUPABASE_URL: $SUPABASE_URL"
echo "SUPABASE_ANON_KEY: ${SUPABASE_ANON_KEY:0:10}..."

# View tracked commits (check Supabase dashboard)

Disable/Uninstall Process

# Disable Git hooks
echo "#!/bin/bash" > .git/hooks/post-commit
chmod +x .git/hooks/post-commit

# Remove environment variables
unset SUPABASE_URL SUPABASE_ANON_KEY PROJECT_ID

# Remove setup script
rm -f setup-git-hooks.sh .env.local

Best Practices

Project Naming

• Use kebab-case for project names
• Keep names descriptive and consistent
• Avoid spaces in project names

Commit Messages

• Write clear, descriptive commit messages
• Use conventional commits format when possible
• Include context about what changed

Environment Setup

• Always set SUPABASE_ANON_KEY before setup
• Use .env.local for local environment variables
• Add .env.local to .gitignore

Integration with Other Tools

GitHub Actions

# .github/workflows/track-commits.yml
name: Track Commits
on: [push]
jobs:
  track:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Track commit
        run: |
          curl -X POST "${{ secrets.SUPABASE_URL }}/rest/v1/rpc/track_git_commit" \
            -H "apikey: ${{ secrets.SUPABASE_ANON_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"p_project_name": "${{ github.repository }}", ...}'

VS Code Integration

// .vscode/tasks.json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Setup Git Tracking",
      "type": "shell",
      "command": "./setup-git-hooks.sh",
      "group": "build"
    }
  ]
}

Maintenance

Regular Tasks

• Monthly: Review tracked projects in Supabase dashboard
• Quarterly: Update setup scripts with new features
• As needed: Add new projects to tracking system

Updates

• Setup script: Update from cursor-rules template
• Environment variables: Keep Supabase keys current
• Git hooks: Test after major Git updates

Quick Reference

Setup Commands (MCP-Enhanced)

# Full setup for new project (MCP handles Supabase automatically)
./setup-git-hooks.sh "project-name"

# Test the setup
git add . && git commit -m "Test commit"

Dashboard Access

• Supabase Dashboard: https://supabase.com/dashboard/project/zeopoimfsxdidkyiucsr
• Project Health: SELECT * FROM project_health_summary
• Recent Activity: SELECT * FROM recent_project_activity

Cursor Commands (MCP-Enhanced)

• "Set up Git tracking" → Automatic setup via MCP
• "Create new Supabase project" → MCP creates project + sets up tracking
• "Track this commit" → Manual tracking via MCP
• "Show project dashboard" → Open Supabase dashboard via MCP