supabase-stateful 0.1.0

package/src/commands/start.js

@@ -0,0 +1,178 @@
+/**
+ * Start command - start Supabase and restore saved state
+ *
+ * Flow:
+ * 1. If already running: check for pending migrations, apply if needed
+ * 2. If not running: start Supabase (with fallbacks for common issues)
+ * 3. Restore saved state if it exists (schema + data from last session)
+ * 4. Run pending migrations ON TOP of existing data
+ *
+ * This order is critical - migrations run on your data, not on an empty database.
+ * E.g., if a teammate added a "rename column" migration, it transforms YOUR data.
+ */
+
+import { execSync, spawnSync } from 'child_process';
+import { restoreState, stateExists } from '../lib/state.js';
+import { isRunning } from '../lib/docker.js';
+import { log } from '../utils/log.js';
+
+export async function start() {
+  log.info('Starting Supabase with stateful development...');
+
+  // Check if already running
+  if (isRunning()) {
+    log.success('Supabase already running');
+    await handleRunningInstance();
+    return;
+  }
+
+  // Start Supabase
+  if (!await startSupabase()) {
+    log.error('Failed to start Supabase');
+    process.exit(1);
+  }
+
+  // Restore saved state FIRST (schema + data from last session)
+  await restoreSavedState();
+
+  // Apply pending migrations ON TOP of existing data
+  await applyMigrations();
+
+  printReady();
+}
+
+/**
+ * Handle when Supabase is already running
+ * Apply any pending migrations on top of existing data
+ */
+async function handleRunningInstance() {
+  // Apply pending migrations on top of existing data
+  await applyMigrations();
+  printReady();
+}
+
+/**
+ * Apply pending migrations ON TOP of existing data
+ * Uses `supabase migration up` instead of `db reset` to preserve data
+ */
+async function applyMigrations() {
+  log.info('Checking for pending migrations...');
+
+  try {
+    const output = execSync('supabase migration list --output json', {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    const pendingCount = (output.match(/"Applied": false/g) || []).length;
+
+    if (pendingCount > 0) {
+      log.info(`Found ${pendingCount} pending migration(s)`);
+      log.info('Applying migrations on top of existing data...');
+
+      // Use `migration up` instead of `db reset` - this applies migrations WITHOUT wiping data
+      const result = spawnSync('supabase', ['migration', 'up'], {
+        stdio: 'inherit',
+        shell: true,
+      });
+
+      if (result.status !== 0) {
+        log.error('Migration failed');
+        process.exit(1);
+      }
+
+      log.success('Migrations applied');
+    } else {
+      log.success('No pending migrations');
+    }
+  } catch {
+    // Migration check failed, try applying anyway
+    log.dim('Could not check migration status, attempting to apply...');
+
+    const result = spawnSync('supabase', ['migration', 'up'], {
+      stdio: 'inherit',
+      shell: true,
+    });
+
+    if (result.status === 0) {
+      log.success('Migrations applied');
+    }
+  }
+}
+
+/**
+ * Start Supabase with fallbacks for common issues
+ */
+async function startSupabase() {
+  log.info('Starting Supabase...');
+
+  // Try normal start first
+  let result = spawnSync('supabase', ['start'], {
+    stdio: 'inherit',
+    shell: true,
+  });
+
+  if (result.status === 0) {
+    return true;
+  }
+
+  log.warn('Standard start failed, trying alternatives...');
+
+  // Try without analytics (logflare often causes health check issues)
+  result = spawnSync('supabase', ['start', '--exclude', 'logflare'], {
+    stdio: 'inherit',
+    shell: true,
+  });
+
+  if (result.status === 0) {
+    log.success('Started without analytics');
+    return true;
+  }
+
+  // Try ignoring health checks
+  result = spawnSync('supabase', ['start', '--ignore-health-check'], {
+    stdio: 'inherit',
+    shell: true,
+  });
+
+  if (result.status === 0) {
+    log.success('Started ignoring health checks');
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Restore saved state if it exists
+ */
+async function restoreSavedState() {
+  if (await stateExists()) {
+    log.info('Found saved state - restoring...');
+
+    try {
+      await restoreState();
+      console.log('');
+      log.success('Previous session restored!');
+      console.log('');
+      console.log('Your test users and data have been restored');
+      console.log('Database schema updated and data preserved');
+    } catch {
+      log.warn('State restoration had some errors (likely duplicates - this is normal)');
+    }
+  } else {
+    log.info('No saved state found');
+    console.log('');
+    console.log('Create test users, then run: supabase-stateful stop');
+    console.log('Your state will be saved for next session');
+  }
+}
+
+/**
+ * Print ready message
+ */
+function printReady() {
+  console.log('');
+  console.log('Access Supabase Studio: http://localhost:54323');
+  log.success('Ready for development!');
+}

package/src/commands/status.js

@@ -0,0 +1,65 @@
+/**
+ * Status command - show current state
+ *
+ * Displays:
+ * - Whether Supabase is running
+ * - Saved state info (exists, size, last modified)
+ * - Configuration details
+ */
+
+import { isRunning } from '../lib/docker.js';
+import { getStateInfo } from '../lib/state.js';
+import { getConfig, configExists } from '../lib/config.js';
+import { log } from '../utils/log.js';
+
+export async function status() {
+  console.log('');
+  console.log('Supabase Stateful Status');
+  console.log('========================');
+  console.log('');
+
+  // Check if initialized
+  if (!await configExists()) {
+    log.warn('Not initialized');
+    console.log('');
+    console.log('Run: supabase-stateful init');
+    return;
+  }
+
+  const config = await getConfig();
+
+  // Supabase status
+  if (isRunning()) {
+    log.success('Supabase: Running');
+  } else {
+    log.info('Supabase: Stopped');
+  }
+
+  // State file status
+  const stateInfo = await getStateInfo();
+  if (stateInfo.exists) {
+    log.success(`State file: ${stateInfo.path}`);
+    console.log(`  Size: ${stateInfo.size}`);
+    console.log(`  Modified: ${stateInfo.modified.toLocaleString()}`);
+  } else {
+    log.info(`State file: Not saved yet`);
+    console.log(`  Path: ${stateInfo.path}`);
+  }
+
+  // Config info
+  console.log('');
+  console.log('Configuration:');
+  console.log(`  Container: ${config.containerName}`);
+  console.log(`  State file: ${config.stateFile}`);
+
+  // Service URLs if running
+  if (isRunning()) {
+    console.log('');
+    console.log('Service URLs:');
+    console.log('  API: http://localhost:54321');
+    console.log('  Studio: http://localhost:54323');
+    console.log('  Database: localhost:54322');
+  }
+
+  console.log('');
+}

package/src/commands/stop.js

@@ -0,0 +1,50 @@
+/**
+ * Stop command - save state, clear auth tokens, stop Supabase
+ *
+ * Flow:
+ * 1. Check if Supabase is running
+ * 2. Save current database state
+ * 3. Clear auth.refresh_tokens (prevents duplicate key errors on next start)
+ * 4. Stop Supabase
+ */
+
+import { saveState, clearAuthTokens } from '../lib/state.js';
+import { isRunning, shell } from '../lib/docker.js';
+import { log } from '../utils/log.js';
+
+export async function stop() {
+  // Check if Supabase is running
+  if (!isRunning()) {
+    log.warn('Supabase is not running');
+    return;
+  }
+
+  log.info('Saving state and stopping Supabase...');
+
+  // Save current database state
+  log.info('Saving local database state...');
+  try {
+    await saveState();
+    log.success('State saved');
+  } catch (err) {
+    log.error(`Failed to save state: ${err.message}`);
+    // Continue anyway - user may want to stop even if save fails
+  }
+
+  // Clear refresh tokens to prevent duplicate key errors on next start
+  log.info('Clearing auth tokens...');
+  if (await clearAuthTokens()) {
+    log.success('Refresh tokens cleared');
+  } else {
+    log.warn('Could not clear refresh tokens (this is okay)');
+  }
+
+  // Stop Supabase
+  log.info('Stopping Supabase...');
+  shell('supabase stop');
+
+  log.success('Supabase stopped cleanly');
+  console.log('');
+  console.log('State saved and auth tokens cleared');
+  console.log('Next time: supabase-stateful start to restore your session');
+}

package/src/commands/sync.js

@@ -0,0 +1,63 @@
+/**
+ * Sync command - export cloud data and apply to local database
+ *
+ * Combines export + local application:
+ * 1. Export cloud data to seed file
+ * 2. Reset local database (applies migrations)
+ * 3. Apply the seed data
+ */
+
+import { spawnSync } from 'child_process';
+import { exportCloudData } from '../lib/cloud.js';
+import { isRunning, psqlFile } from '../lib/docker.js';
+import { log } from '../utils/log.js';
+
+export async function sync(options) {
+  log.info('Syncing cloud data to local...');
+
+  // Check if Supabase is running
+  if (!isRunning()) {
+    log.error('Supabase is not running');
+    console.log('');
+    console.log('Start it first: supabase-stateful start');
+    process.exit(1);
+  }
+
+  // Export cloud data
+  let seedFile;
+  try {
+    seedFile = await exportCloudData({
+      sample: options.sample,
+      tables: options.tables,
+    });
+  } catch (err) {
+    log.error(`Export failed: ${err.message}`);
+    process.exit(1);
+  }
+
+  // Reset local database to apply migrations
+  log.info('Resetting local database...');
+  const resetResult = spawnSync('supabase', ['db', 'reset'], {
+    stdio: 'inherit',
+    shell: true,
+  });
+
+  if (resetResult.status !== 0) {
+    log.error('Database reset failed');
+    process.exit(1);
+  }
+
+  // Apply the seed data
+  log.info('Applying seed data...');
+  try {
+    await psqlFile(seedFile);
+  } catch {
+    log.warn('Some seed data may have failed (duplicates - this is normal)');
+  }
+
+  console.log('');
+  log.success('Sync complete!');
+  console.log('');
+  console.log('Your local database now has cloud data');
+  console.log('Access Studio: http://localhost:54323');
+}

package/src/lib/cloud.js

@@ -0,0 +1,169 @@
+/**
+ * Cloud data export - pull data from a remote Supabase instance
+ *
+ * Requires environment variables:
+ * - SUPABASE_URL - Your Supabase project URL
+ * - SUPABASE_SERVICE_ROLE_KEY - Service role key for data access
+ *
+ * Based on scouty's data-export.js
+ */
+
+import fs from 'fs/promises';
+import { log } from '../utils/log.js';
+
+// Tables to export in dependency order (parent tables first)
+const DEFAULT_TABLES = [
+  'coaches',
+  'client_profiles',
+  'products',
+  'plans',
+  'coach_availability',
+  'plan_groups',
+  'subscriptions',
+  'enquiries',
+  'purchases',
+  'payments',
+  'bookings',
+  'reviews',
+  'coach_reviews',
+  'events',
+];
+
+/**
+ * Export data from cloud Supabase to a seed file
+ */
+export async function exportCloudData(options = {}) {
+  const { sample = false, tables = null, output = 'supabase/seed-data.sql' } = options;
+
+  // Check for required env vars
+  const url = process.env.SUPABASE_URL || process.env.NEXT_PUBLIC_SUPABASE_URL;
+  const key = process.env.SUPABASE_SERVICE_ROLE_KEY;
+
+  if (!url || !key) {
+    log.error('Missing environment variables');
+    console.log('');
+    console.log('Required:');
+    console.log('  SUPABASE_URL (or NEXT_PUBLIC_SUPABASE_URL)');
+    console.log('  SUPABASE_SERVICE_ROLE_KEY');
+    process.exit(1);
+  }
+
+  log.info('Connecting to cloud Supabase...');
+  log.dim(`URL: ${url}`);
+
+  // Determine which tables to export
+  const tablesToExport = tables ? tables.split(',').map(t => t.trim()) : DEFAULT_TABLES;
+  const limit = sample ? 100 : null;
+
+  log.info(`Exporting ${tablesToExport.length} tables${sample ? ' (sample: 100 rows each)' : ''}...`);
+
+  const allData = [];
+
+  for (const table of tablesToExport) {
+    const tableData = await fetchTable(url, key, table, limit);
+    if (tableData) {
+      allData.push(tableData);
+      log.success(`  ${table}: ${tableData.data.length} rows`);
+    } else {
+      log.dim(`  ${table}: skipped (not found or empty)`);
+    }
+  }
+
+  // Generate SQL file
+  const sql = generateSql(allData, sample);
+  await fs.writeFile(output, sql);
+
+  const totalRows = allData.reduce((sum, t) => sum + t.data.length, 0);
+  log.success(`Exported ${totalRows} total rows to ${output}`);
+
+  return output;
+}
+
+/**
+ * Fetch data from a single table
+ */
+async function fetchTable(url, key, table, limit) {
+  try {
+    let apiUrl = `${url}/rest/v1/${table}?select=*`;
+    if (limit) {
+      apiUrl += `&limit=${limit}`;
+    }
+
+    const response = await fetch(apiUrl, {
+      headers: {
+        apikey: key,
+        Authorization: `Bearer ${key}`,
+      },
+    });
+
+    if (!response.ok) {
+      return null;
+    }
+
+    const data = await response.json();
+    if (!data || data.length === 0) {
+      return null;
+    }
+
+    return { table, data };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Generate SQL INSERT statements from exported data
+ */
+function generateSql(allData, sample) {
+  const timestamp = new Date().toISOString();
+
+  let sql = `-- =============================================================================
+-- Cloud Data Export
+-- =============================================================================
+-- Generated: ${timestamp}
+-- Mode: ${sample ? 'Sample (100 rows per table)' : 'Full export'}
+--
+-- Use this file to seed your local database with cloud data
+-- =============================================================================
+
+SET session_replication_role = replica;
+
+`;
+
+  for (const { table, data } of allData) {
+    if (data.length === 0) continue;
+
+    const columns = Object.keys(data[0]);
+    const columnList = columns.map(c => `"${c}"`).join(', ');
+
+    sql += `-- ${table}\n`;
+    sql += `INSERT INTO public.${table} (${columnList}) VALUES\n`;
+
+    const valueRows = data.map((row, i) => {
+      const values = columns.map(col => formatValue(row[col])).join(', ');
+      const comma = i < data.length - 1 ? ',' : '';
+      return `  (${values})${comma}`;
+    });
+
+    sql += valueRows.join('\n');
+    sql += '\nON CONFLICT DO NOTHING;\n\n';
+  }
+
+  sql += `SET session_replication_role = DEFAULT;\n`;
+
+  return sql;
+}
+
+/**
+ * Format a value for SQL INSERT
+ */
+function formatValue(value) {
+  if (value === null || value === undefined) return 'NULL';
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  if (typeof value === 'number') return String(value);
+  if (typeof value === 'object') {
+    return `'${JSON.stringify(value).replace(/'/g, "''")}'::jsonb`;
+  }
+  // String - escape single quotes
+  return `'${String(value).replace(/'/g, "''")}'`;
+}

package/src/lib/config.js

@@ -0,0 +1,75 @@
+/**
+ * Configuration file management
+ *
+ * Handles the .supabase-stateful.json config file that stores:
+ * - stateFile: where to save the database state (default: supabase/local-state.sql)
+ * - containerName: the docker container name (e.g., supabase_db_myproject)
+ */
+
+import fs from 'fs/promises';
+
+const CONFIG_FILE = '.supabase-stateful.json';
+
+const DEFAULT_CONFIG = {
+  stateFile: 'supabase/local-state.sql',
+  containerName: null,
+};
+
+/**
+ * Load config from .supabase-stateful.json
+ * Falls back to defaults if file doesn't exist
+ */
+export async function getConfig() {
+  try {
+    const content = await fs.readFile(CONFIG_FILE, 'utf8');
+    return { ...DEFAULT_CONFIG, ...JSON.parse(content) };
+  } catch {
+    return DEFAULT_CONFIG;
+  }
+}
+
+/**
+ * Save config to .supabase-stateful.json
+ */
+export async function saveConfig(config) {
+  await fs.writeFile(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n');
+}
+
+/**
+ * Check if config file exists (used to detect if init has been run)
+ */
+export async function configExists() {
+  try {
+    await fs.access(CONFIG_FILE);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Generic file exists check
+ */
+export async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Append a line to a file if not already present
+ * Used to add state file to .gitignore
+ */
+export async function appendIfMissing(filePath, line) {
+  try {
+    const content = await fs.readFile(filePath, 'utf8');
+    if (!content.includes(line)) {
+      await fs.appendFile(filePath, `\n${line}\n`);
+    }
+  } catch {
+    await fs.writeFile(filePath, `${line}\n`);
+  }
+}

package/src/lib/docker.js

@@ -0,0 +1,96 @@
+/**
+ * Docker and shell command helpers
+ *
+ * Provides utilities for:
+ * - Running commands inside the Supabase postgres container (psql, pg_dump)
+ * - Running shell commands (supabase start/stop)
+ * - Checking if Supabase containers are running
+ */
+
+import { execSync, spawnSync } from 'child_process';
+import { getConfig } from './config.js';
+
+/**
+ * Get the Supabase postgres container name from config
+ */
+export async function getContainerName() {
+  const config = await getConfig();
+  return config.containerName;
+}
+
+/**
+ * Run a psql command inside the Supabase postgres container
+ * Returns the command output
+ */
+export async function psql(sql) {
+  const container = await getContainerName();
+  return execSync(
+    `docker exec ${container} psql -U postgres -d postgres -c "${sql}"`,
+    { encoding: 'utf8' }
+  );
+}
+
+/**
+ * Run pg_dump inside the container and return the SQL output
+ */
+export async function pgDump(schemas = ['public', 'auth']) {
+  const container = await getContainerName();
+  const schemaFlags = schemas.map(s => `--schema=${s}`).join(' ');
+
+  return execSync(
+    `docker exec ${container} pg_dump -U postgres -d postgres --data-only --inserts ${schemaFlags}`,
+    { encoding: 'utf8', maxBuffer: 50 * 1024 * 1024 } // 50MB buffer for large exports
+  );
+}
+
+/**
+ * Copy a file into the container and run psql on it
+ */
+export async function psqlFile(localPath) {
+  const container = await getContainerName();
+
+  // Copy file into container
+  execSync(`docker cp "${localPath}" "${container}:/tmp/state.sql"`);
+
+  // Run psql on the file
+  return execSync(
+    `docker exec ${container} psql -U postgres -d postgres -f /tmp/state.sql`,
+    { encoding: 'utf8', maxBuffer: 50 * 1024 * 1024 }
+  );
+}
+
+/**
+ * Run a shell command with output shown to user
+ */
+export function shell(cmd) {
+  return spawnSync(cmd, {
+    shell: true,
+    stdio: 'inherit',
+  });
+}
+
+/**
+ * Run a shell command and capture output
+ */
+export function shellCapture(cmd) {
+  try {
+    return execSync(cmd, { encoding: 'utf8' });
+  } catch (err) {
+    return err.stdout || '';
+  }
+}
+
+/**
+ * Check if Supabase containers are running
+ */
+export function isRunning() {
+  try {
+    const output = execSync('docker ps --format "{{.Names}}"', {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'], // Suppress stderr (Docker not running errors)
+    });
+    return output.includes('supabase_db_');
+  } catch {
+    return false;
+  }
+}