supabase-stateful 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anthony Grant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# supabase-stateful
+
+> Persistent local state for Supabase development
+
+**Note:** Currently supports Next.js (App Router) only. The core state persistence works with any framework, but the generated client files are Next.js specific.
+
+## The Problem
+
+Local Supabase is **stateless by default**. Stop it, lose everything. Restart, get `duplicate key` errors.
+
+## The Solution
+
+```bash
+npx supabase-stateful setup   # Interactive setup
+
+npm run supabase:start        # Restores your previous session
+# ... develop, create test users, add data ...
+npm run supabase:stop         # Saves state for next time
+```
+
+Next time you start, **everything is back** - test users, data, relationships intact.
+
+## Quick Start
+
+**Prerequisites:** [Supabase CLI](https://supabase.com/docs/guides/cli) and [Docker](https://docs.docker.com/desktop)
+
+```bash
+# 1. Have a Supabase project (run `supabase init` if you don't)
+
+# 2. Run interactive setup
+npx supabase-stateful setup
+
+# 3. Start developing
+npm run dev:local             # or ./scripts/dev-local.sh for graceful shutdown
+```
+
+The setup wizard will:
+- Install required dependencies (`@supabase/ssr`, `@supabase/supabase-js`, `concurrently`)
+- Create Supabase client files with local/production switching (Next.js only)
+- Add npm scripts for stateful start/stop
+- Generate a graceful shutdown script (Ctrl+C saves state automatically)
+- Optionally install GitHub Actions for CI/CD migrations
+
+## Daily Workflow
+
+```bash
+npm run dev:local           # Start with local Supabase (restores your data)
+npm run supabase:stop       # Save state and stop (or Ctrl+C with dev-local.sh)
+```
+
+## How It Works
+
+| On Stop | On Start |
+|---------|----------|
+| Export database state | Start Supabase |
+| Clear auth tokens | Restore saved state |
+| Stop Supabase | Apply pending migrations on top |
+
+Migrations run **on top of your existing data**, not on an empty database.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `setup` | Interactive setup wizard |
+| `start` | Start and restore state |
+| `stop` | Save state and stop |
+| `status` | Show current status |
+
+## Deployment
+
+The setup wizard can install a GitHub Actions workflow for CI/CD:
+
+```
+Push to main → Run migrations on production → Deploy app
+```
+
+1. **Migrations job** - Applies your local `supabase/migrations/*.sql` files to your production Supabase database
+2. **Deploy job** - Builds and deploys your app to Vercel (optional)
+
+See [CI/CD with GitHub Actions](docs/github-actions.md) for setup details and required secrets.
+
+## Documentation
+
+- [New Project Setup](docs/new-project.md)
+- [Existing Project Setup](docs/existing-project.md)
+- [CI/CD with GitHub Actions](docs/github-actions.md)
+- [Troubleshooting](docs/troubleshooting.md)
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import { init } from '../src/commands/init.js';
+import { setup } from '../src/commands/setup.js';
+import { start } from '../src/commands/start.js';
+import { stop } from '../src/commands/stop.js';
+import { status } from '../src/commands/status.js';
+import { sync } from '../src/commands/sync.js';
+import { exportData } from '../src/commands/export.js';
+
+program
+  .name('supabase-stateful')
+  .description('Persistent local state for Supabase development')
+  .version('0.1.0');
+
+program
+  .command('init')
+  .description('Initialize supabase-stateful (basic - just adds npm scripts)')
+  .action(init);
+
+program
+  .command('setup')
+  .description('Full setup - creates Supabase client files + npm scripts')
+  .option('--force', 'Overwrite existing files')
+  .option('-y, --yes', 'Skip interactive prompts (auto-confirm defaults)')
+  .action(setup);
+
+program
+  .command('start')
+  .description('Start Supabase and restore saved state')
+  .action(start);
+
+program
+  .command('stop')
+  .description('Save state, clear auth tokens, and stop Supabase')
+  .action(stop);
+
+program
+  .command('status')
+  .description('Show current status')
+  .action(status);
+
+program
+  .command('sync')
+  .description('Sync cloud data to local database')
+  .option('--sample', 'Limit to 100 rows per table')
+  .option('--tables <tables>', 'Comma-separated list of tables')
+  .action(sync);
+
+program
+  .command('export')
+  .description('Export cloud data to seed file')
+  .option('--sample', 'Limit to 100 rows per table')
+  .option('--tables <tables>', 'Comma-separated list of tables')
+  .option('--output <path>', 'Output file path')
+  .action(exportData);
+
+program.parse();

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "supabase-stateful",
+  "version": "0.1.0",
+  "description": "Persistent local state for Supabase development",
+  "type": "module",
+  "bin": {
+    "supabase-stateful": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "keywords": [
+    "supabase",
+    "local",
+    "development",
+    "database",
+    "state",
+    "persistence"
+  ],
+  "author": "Anthony Grant",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agrant2711/supabase-stateful"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "toml": "^3.0.0"
+  }
+}

package/src/commands/export.js

@@ -0,0 +1,34 @@
+/**
+ * Export command - export cloud data to a seed file
+ *
+ * Options:
+ * --sample    Limit to 100 rows per table
+ * --tables    Comma-separated list of tables
+ * --output    Output file path (default: supabase/seed-data.sql)
+ */
+
+import { exportCloudData } from '../lib/cloud.js';
+import { log } from '../utils/log.js';
+
+export async function exportData(options) {
+  log.info('Exporting cloud data...');
+
+  try {
+    const output = await exportCloudData({
+      sample: options.sample,
+      tables: options.tables,
+      output: options.output || 'supabase/seed-data.sql',
+    });
+
+    console.log('');
+    log.success('Export complete!');
+    console.log('');
+    console.log('Next steps:');
+    console.log('  1. Review the generated seed file');
+    console.log('  2. Run: supabase-stateful sync  (to apply to local)');
+    console.log(`  Or manually: supabase db reset && psql < ${output}`);
+  } catch (err) {
+    log.error(`Export failed: ${err.message}`);
+    process.exit(1);
+  }
+}

package/src/commands/init.js

@@ -0,0 +1,89 @@
+/**
+ * Init command - set up supabase-stateful in a project
+ *
+ * Steps:
+ * 1. Check for supabase/config.toml (must have run 'supabase init' first)
+ * 2. Parse project name from config
+ * 3. Create .supabase-stateful.json with container name
+ * 4. Add npm scripts to package.json
+ * 5. Add state file to .gitignore
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import toml from 'toml';
+import { log } from '../utils/log.js';
+import { saveConfig, fileExists, appendIfMissing, configExists } from '../lib/config.js';
+
+export async function init() {
+  log.info('Initializing supabase-stateful...');
+
+  // Check if already initialized
+  if (await configExists()) {
+    log.warn('Already initialized (.supabase-stateful.json exists)');
+    return;
+  }
+
+  // Check for supabase project
+  const supabaseConfigPath = 'supabase/config.toml';
+  if (!await fileExists(supabaseConfigPath)) {
+    log.error('No supabase/config.toml found');
+    console.log('');
+    console.log('Run "supabase init" first to create a Supabase project');
+    process.exit(1);
+  }
+
+  // Parse project name from supabase config
+  let projectName;
+  try {
+    const configContent = await fs.readFile(supabaseConfigPath, 'utf8');
+    const config = toml.parse(configContent);
+    projectName = config.project_id || path.basename(process.cwd());
+  } catch {
+    projectName = path.basename(process.cwd());
+  }
+
+  log.info(`Detected project: ${projectName}`);
+
+  // Create config file
+  const statefulConfig = {
+    stateFile: 'supabase/local-state.sql',
+    containerName: `supabase_db_${projectName}`,
+  };
+  await saveConfig(statefulConfig);
+  log.success('Created .supabase-stateful.json');
+
+  // Update package.json with npm scripts
+  if (await fileExists('package.json')) {
+    try {
+      const pkgContent = await fs.readFile('package.json', 'utf8');
+      const pkg = JSON.parse(pkgContent);
+
+      pkg.scripts = pkg.scripts || {};
+      pkg.scripts['supabase:start'] = 'supabase-stateful start';
+      pkg.scripts['supabase:stop'] = 'supabase-stateful stop';
+      pkg.scripts['supabase:status'] = 'supabase-stateful status';
+
+      await fs.writeFile('package.json', JSON.stringify(pkg, null, 2) + '\n');
+      log.success('Added npm scripts to package.json');
+    } catch (err) {
+      log.warn(`Could not update package.json: ${err.message}`);
+    }
+  }
+
+  // Add state file to .gitignore
+  await appendIfMissing('.gitignore', 'supabase/local-state.sql');
+  log.success('Added state file to .gitignore');
+
+  console.log('');
+  log.success('Initialized!');
+  console.log('');
+  console.log('Usage:');
+  console.log('  npm run supabase:start   Start and restore saved state');
+  console.log('  npm run supabase:stop    Save state and stop');
+  console.log('  npm run supabase:status  Show current status');
+  console.log('');
+  console.log('Or run directly:');
+  console.log('  npx supabase-stateful start');
+  console.log('  npx supabase-stateful stop');
+}