@t1mmen/srtd 0.0.0-next-20251227013823 → 0.0.0-next-20251227065529

package/README.md

@@ -1,363 +1,184 @@
-# `srtd` 🪄 Supabase Repeatable Template Definitions
+# `srtd` — Live-Reloading SQL Templates for Supabase
 
-
-
-> Live-reloading SQL templates for [Supabase](https://supabase.com) projects. DX supercharged! 🚀
+> Edit `my_function.sql` → save → it's running on your local database. No migration dance, no restart. When you're ready to ship, build to migrations that show real diffs in PRs.
 
 [![NPM Version](https://img.shields.io/npm/v/%40t1mmen%2Fsrtd)](https://www.npmjs.com/package/@t1mmen/srtd)
 [![Downloads](https://img.shields.io/npm/dt/%40t1mmen%2Fsrtd)](https://www.npmjs.com/package/@t1mmen/srtd)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI/CD](https://github.com/t1mmen/srtd/actions/workflows/ci.yml/badge.svg)](https://github.com/t1mmen/srtd/actions/workflows/ci.yml)
-[![codecov](https://codecov.io/gh/t1mmen/srtd/graph/badge.svg?token=CIMAZ55KCJ)](https://codecov.io/gh/t1mmen/srtd)
-
-
-[![video demo](./readme-demo.gif)](./readme-demo.gif)
-
 
-`srtd` enhances the [Supabase](https://supabase.com) DX by adding **live-reloading SQL** from templates into local db.
+[![demo](./readme-demo.gif)](./readme-demo.gif)
 
-**Templates act as single-source-of-truth of your database objects**, that `build` to regular SQL migrations; This makes for sane code reviews and functional change history, (e.g `git blame` works as expected).
 
+## Why This Exists
 
-📖 Blog: [Introducing `srtd`: Live-Reloading SQL Templates for Supabase](https://timm.stokke.me/blog/srtd-live-reloading-and-sql-templates-for-supabase)
+Two things drove me crazy while building [Timely](https://www.timely.com)'s [Memory Engine](https://www.timely.com/memory-app) on Supabase:
 
-### Why This Exists 🤔
+**1. Iterating on database logic was painfully slow.**
+Change a function → create migration → apply → hit an error → create another migration → apply → repeat. I was spending more time on migration ceremony than actual logic.
 
-While building [Timely](https://www.timely.com)'s next-generation [Memory Engine](https://www.timely.com/memory-app) on [Supabase](https://supabase.com), we found ourselves facing two major annoyances:
+**2. Code reviews for database changes were useless.**
+Every function change showed up as a complete rewrite in git. Reviewers couldn't see what actually changed. `git blame` was worthless.
 
-1. Code reviews were painful - function changes showed up as complete rewrites, `git blame` was useless
-2. Designing and iterating on database changes locally was full of friction, no matter which workflow we tried
+After [searching](https://news.ycombinator.com/item?id=37755076) for [two years](https://news.ycombinator.com/item?id=36007640), I built `srtd`.
 
-I spent [nearly two](https://news.ycombinator.com/item?id=37755076) [years looking](https://news.ycombinator.com/item?id=36007640) for something pre-existing, to no avail. Sufficiently fed up, I paired with [Claude](https://claude.ai) to eliminate these annoyances.
 
-Say hello to `srtd`.
+## How It Works
 
-[![screenshot of srtd](./readme-screenshot.png)](./readme-screenshot.png)
+Your functions, views, RLS policies, and triggers live in **template files**—plain SQL that's the source of truth.
 
-## Key Features ✨
-
-- **Live Reload**: Changes to your SQL templates instantly update your local database
-- **Templates as source of truth**: Templates are the source of (non-mutable) database objects
-- **Just SQL**: Templates as just SQL, and `build` to standard [Supabase](https://supabase.com) migrations when you're ready to ship
-- **Sane code reviews**: Templates evolve like regular code, with diffs in PR's working `git blame`.
-- **Developer Friendly**: Interactive CLI with visual feedback for all operations.
-
-Built specifically for projects using the standard [Supabase](https://supabase.com) stack (but probably works alright for other Postgres-based projects, too).
+```
+supabase/migrations-templates/
+├── notify_changes.sql
+├── user_policies.sql
+└── active_subscriptions.sql
+```
 
-## Quick Start 🚀
+**During development:** `srtd watch` monitors your templates. Save a file, it applies to your local database instantly. Like hot reload, but for Postgres.
 
-### Requirements
+**When you're ready to ship:** `srtd build` generates timestamped migrations from your templates.
 
-- Node.js v20.18.1 or higher
-- [Supabase](https://supabase.com) project initialized (in `/supabase`).
+```
+Edit template → Instantly applies locally → Build migration → Deploy
+```
 
-### Installation
 
+## Quick Start
 
 ```bash
-# Global installation
 npm install -g @t1mmen/srtd
-
-# Project installation
-npm install --save-dev @t1mmen/srtd
-
-# Or run directly
-npx @t1mmen/srtd
-```
-
-### Setup
-
-```bash
 cd your-supabase-project
-npx @t1mmen/srtd init # Creates srtd.config.json, not required
-```
-
-### Create Your First Template
 
-Create `supabase/migrations-templates/my_function.sql`:
-
-```sql
-DROP FUNCTION IF EXISTS public.my_function; -- Makes it easier to change args later
-CREATE FUNCTION my_function()
-RETURNS void AS $$
-BEGIN
-  -- Your function logic here
-END;
+# Create a template
+mkdir -p supabase/migrations-templates
+cat > supabase/migrations-templates/hello.sql << 'EOF'
+DROP FUNCTION IF EXISTS hello;
+CREATE FUNCTION hello() RETURNS text AS $$
+BEGIN RETURN 'Hello from srtd!'; END;
 $$ LANGUAGE plpgsql;
+EOF
+
+# Start watch mode
+srtd watch
 ```
 
-### Development Workflow
+Edit `hello.sql`, save, and it's live on your local database. No migration file, no restart, no waiting.
 
-1. Start watch mode:
-```bash
-npx @t1mmen/srtd watch  # Changes auto-apply to local database
-```
+When ready to deploy:
 
-2. When ready to deploy:
 ```bash
-npx @t1mmen/srtd build     # Creates timestamped migration file
-supabase migration up      # Apply using Supabase CLI
+srtd build            # Creates supabase/migrations/20241226_srtd-hello.sql
+supabase migration up # Deploy with Supabase CLI
 ```
 
-> [!TIP]
-> To reduce noise in PR's, consider adding `supabase/migrations/*srtd*.sql linguist-generated=true` to your [`.gitattributes` file.](https://docs.github.com/en/repositories/working-with-files/managing-files/customizing-how-changed-files-appear-on-github) (unless you manually edit the generated files)
-
 
-## The Power of Templates 💪
+## The Diff Problem, Solved
 
-Without templates, the smallest change to a function would show up as a complete rewrite in your version control system. With templates, the diff is clear and concise.
+Without templates, changing one line in a function means your PR shows a complete rewrite—the old `DROP` + `CREATE` replaced by a new one. Reviewers have to read the whole thing to spot your change.
 
+With templates, your PR shows what you actually changed:
 
-### Perfect For 🎯
-
-✅ Database functions:
 ```diff
-  -- Event notifications
-  DROP FUNCTION IF EXISTS notify_changes;
-  CREATE FUNCTION notify_changes()
-  RETURNS trigger AS $$
+  CREATE FUNCTION calculate_total(order_id uuid)
+  RETURNS numeric AS $$
   BEGIN
-    PERFORM pg_notify(
-      'changes',
-      json_build_object('table', TG_TABLE_NAME, 'id', NEW.id)::text
-    );
-+   RAISE NOTICE 'Notified changes for %', TG_TABLE_NAME; -- Debug logging
-    RETURN NEW;
+-   RETURN (SELECT SUM(price) FROM order_items WHERE order_id = $1);
++   RETURN (SELECT SUM(price * quantity) FROM order_items WHERE order_id = $1);
   END;
   $$ LANGUAGE plpgsql;
 ```
 
-✅ Row-Level Security (RLS):
-```diff
-  -- Replace/update policies safely
-  DROP POLICY IF EXISTS "workspace_access" ON resources;
-  CREATE POLICY "workspace_access" ON resources
-    USING (workspace_id IN (
-      SELECT id FROM workspaces
-      WHERE organization_id = auth.organization_id()
-+       AND auth.user_role() NOT IN ('pending')
-    ));
-```
+`git blame` works. Code reviews are useful. Your database logic is treated like real code.
 
-✅ Views for data abstraction:
-```diff
-  CREATE OR REPLACE VIEW active_subscriptions AS
-  SELECT
-    s.*,
-    p.name as plan_name,
-    p.features
-  FROM subscriptions s
-  JOIN plans p ON p.id = s.plan_id
--  WHERE s.status = 'active';
-+  WHERE s.status = 'active'
-+    AND s.expires_at > CURRENT_TIMESTAMP;
-```
 
-✅ Roles and Permissions:
-```diff
-  -- Revoke all first for clean state
-  REVOKE ALL ON ALL TABLES IN SCHEMA public FROM public;
+## Commands
 
-  -- Grant specific access
-  GRANT USAGE ON SCHEMA public TO authenticated;
-  GRANT SELECT ON ALL TABLES IN SCHEMA public TO authenticated;
-+ GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO admin;
-```
+| Command | What it does |
+|---------|--------------|
+| `srtd` | Interactive menu |
+| `srtd watch` | Live reload—applies templates on save |
+| `srtd build` | Generate migration files |
+| `srtd apply` | Apply all templates once (no watch) |
+| `srtd register` | Mark templates as already deployed |
+| `srtd promote` | Convert `.wip` template to buildable |
+| `srtd clear` | Reset build state |
 
-✅ Safe Type Extensions:
-```diff
- DO $$
- BEGIN
-   -- Add new enum values idempotently
-   IF NOT EXISTS (SELECT 1 FROM pg_type WHERE typname = 'notification_type') THEN
-     CREATE TYPE notification_type AS ENUM ('email', 'sms');
-   END IF;
-
-   -- Extend existing enum safely
-   ALTER TYPE notification_type ADD VALUE IF NOT EXISTS 'push';
-   ALTER TYPE notification_type ADD VALUE IF NOT EXISTS 'pusher';
-   ALTER TYPE notification_type ADD VALUE IF NOT EXISTS 'webhook';
-+  ALTER TYPE notification_type ADD VALUE IF NOT EXISTS 'whatsapp';
- END $$;
-```
+Options: `build --force` rebuilds all, `build --bundle` combines into single migration.
 
-✅ Triggers
-```diff
- DROP TRIGGER IF EXISTS on_new_user ON auth.users;
- DROP FUNCTION IF EXISTS public.setup_new_user;
-
- CREATE FUNCTION public.setup_new_user() RETURNS TRIGGER LANGUAGE plpgsql SECURITY DEFINER
- SET search_path = public AS $$
- BEGIN
-   -- Existing logic for new users
-
-+  -- Your new changes go here..
- END;
- $$;
-
- CREATE TRIGGER on_new_user AFTER INSERT ON auth.users FOR EACH ROW EXECUTE PROCEDURE public.setup_new_user ();
-```
 
-> [!TIP]
-> You don't need to specifying parameters in drop functions. E.g `DROP FUNCTION IF EXISTS public.my_function;`. This ensures you don't end up with multiple functions with the same name, but different parameters.
+## What Works as Templates
 
-### Not Recommended For:
-* ❌ Table structures
-* ❌ Indexes
-* ❌ Data modifications
-* ❌ Non-idempotent operations
+Templates need to be **idempotent**—safe to run multiple times. This works great for:
 
-Use regular [Supabase](https://supabase.com) migrations for these cases.
+| Object | Pattern |
+|--------|---------|
+| Functions | `DROP FUNCTION IF EXISTS` + `CREATE FUNCTION` |
+| Views | `CREATE OR REPLACE VIEW` |
+| RLS Policies | `DROP POLICY IF EXISTS` + `CREATE POLICY` |
+| Triggers | Drop + recreate trigger and function |
+| Roles | `REVOKE ALL` + `GRANT` |
+| Enums | `ADD VALUE IF NOT EXISTS` |
 
+**Not for templates:** Table structures, indexes, data modifications—use regular migrations for those.
 
-## Commands 🎮
 
-### Interactive Mode
+## WIP Templates
 
-Running `npx @t1mmen/srtd` without arguments opens an interactive menu. All commands can also be run directly:
+Experimenting? Add `.wip.sql` extension:
 
-- 👀 `srtd watch` - Watch and auto-apply changes
-- 🏗️  `srtd build [--force] [--bundle]` - Generate migrations from templates
-- ▶️  `srtd apply [--force]` - Apply templates directly to local database
-- ✍️  `srtd register [file.sql...]` - Mark templates as already built
-- 🚀  `srtd promote - [file.sql ...]` - Promote WIP template to buildable templates
-- 🧹 `srtd clear` - Clear build logs or reset configuration
-
-> [!IMPORTANT]
-> `watch` and `apply` commands modify your local database directly and don't clean up after themselves. Use with caution!
-
-## Configuration 📝
-
-`srtd.config.json` can be created with `init` command. It is not necessary, if the defaults suit your needs.
-
-```jsonc
-{
-  // Prevents building templates with this extension
-  "wipIndicator": ".wip",
-
-  // Migration file naming: 20211001000000_srtd-my_function.sql
-  "migrationPrefix": "srtd",
-
-  // Template discovery
-  "filter": "**/*.sql",
-
-  // Migration file comments
-  "banner": "You very likely **DO NOT** want to manually edit this generated file.",
-  "footer": "",
-
-  // Wrap migrations in transaction
-  "wrapInTransaction": true,
-
-  // File paths
-  "templateDir": "supabase/migrations-templates",
-  "migrationDir": "supabase/migrations",
-  "buildLog": "supabase/migrations-templates/.buildlog.json",
-  "localBuildLog": "supabase/migrations-templates/.buildlog.local.json",
-
-  // Database connection
-  "pgConnection": "postgresql://postgres:postgres@localhost:54322/postgres"
-}
 ```
-
-## Other Features 🔧
-
-### Work in Progress Templates
-
-Add `.wip.sql` extension to prevent migration generation:
-```bash
-my_function.wip.sql  # Only applied locally, never built
+my_experiment.wip.sql  → Applies locally, never builds to migration
 ```
 
-Make a WIP template buildable as migration by renaming it, or using the `promote` command:
-```bash
-npx @t1mmen/srtd promote my_function.wip.sql
-```
+When it's ready: `srtd promote my_experiment.wip.sql`
 
-### Register Existing Objects
 
-Registering a template is useful when you're creating templates for what is already in your database. This avoids generating migrations on `build` (until they're changed)
+## Existing Projects
 
-```bash
-# Register specific template
-npx @t1mmen/srtd register my_function.sql another_fn.sql
+Already have functions in your database? Create templates for them, then:
 
-# Interactive multi-select UI
-npx @t1mmen/srtd register
+```bash
+srtd register existing_function.sql another_one.sql
 ```
 
-This can be useful when setting up `srtd` for an existing project, where you may have hundreds of existing functions, views, etc that you want as templates, but don't want to generate migrations until changed later.
+This tells srtd "these are already deployed—don't generate migrations until they change."
 
-### Template State Management
 
-The state of templates are stored to..
+## Configuration
 
-- [`.buildlog.json`](https://github.com/t1mmen/srtd/blob/main/supabase/migrations-templates/.srtd.buildlog.json) - Migration build state (commit this)
-- `.buildlog.local.json` - Local database state (add to `.gitignore`)
+Defaults work for standard Supabase projects. Optional `srtd.config.json`:
 
-This helps `srtd` identify when templates are changed, to only `build` (as migrations) or `apply`  the necessary changes (directly to local db).
-
-## Development 🛠️
-
-### Local Setup
-
-```bash
-# Clone and install
-git clone https://github.com/stokke/srtd.git
-cd srtd
-npm install
-
-# Development
-npm run dev     # Watch mode
-npm test        # Run tests
-npm start       # Run CLI
-npm start:link  # Build, npm link, and run CLI
-
-# Quality Checks
-npm run typecheck       # Type checking
-npm run lint            # Lint and fix
-npm run format          # Format code
-npm run test:coverage   # Test coverage
+```jsonc
+{
+  "templateDir": "supabase/migrations-templates",
+  "migrationDir": "supabase/migrations",
+  "pgConnection": "postgresql://postgres:postgres@localhost:54322/postgres",
+  "wipIndicator": ".wip",
+  "wrapInTransaction": true
+}
 ```
 
-## Contributing 🤝
-
-While feature-complete for our needs, we welcome:
 
-- 🐛 Bug fixes and reliability improvements
-- 📚 Documentation improvements
-- ✅ Test coverage enhancements
-- ⚡️ Performance optimizations
+## State Tracking
 
-### Contribution Process
+| File | Purpose | Git |
+|------|---------|-----|
+| `.buildlog.json` | What's been built to migrations | Commit |
+| `.buildlog.local.json` | What's applied to your local DB | Gitignore |
 
-1. Create a [changeset](https://github.com/changesets/changesets) (`npm run changeset`)
-2. Ensure tests pass (`npm test`)
-3. Follow existing code style
-4. Update documentation
 
-Note: New features are evaluated based on alignment with project scope.
+## Contributing
 
-## Built With 🛠️
+Bug fixes, docs, and test coverage welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).
 
-### CLI
-- [Commander.js](https://github.com/tj/commander.js) - CLI framework
-- [Inquirer](https://github.com/SBoudrias/Inquirer.js) - Interactive prompts
-- [Ora](https://github.com/sindresorhus/ora) - Terminal spinners
-- [Chalk](https://github.com/chalk/chalk) - Terminal styling
-- [Figures](https://github.com/sindresorhus/figures) - Unicode symbols
+For development: [CLAUDE.md](./CLAUDE.md).
 
-### Core
-- [Chokidar](https://github.com/paulmillr/chokidar) - File watcher
-- [Zod](https://zod.dev/) - Schema validation
-- [update-notifier](https://github.com/sindresorhus/update-notifier) - Version checks
 
+## More
 
-## License
-
-MIT License - see [LICENSE](LICENSE) file.
+- [Blog post](https://timm.stokke.me/blog/srtd-live-reloading-and-sql-templates-for-supabase)
+- [MIT License](./LICENSE)
 
 ---
 
-Made with 🪄 by [Timm Stokke](https://timm.stokke.me) & [Claude Sonnet](https://claude.ai)
-
-[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/t1mmen)
+Built by [Timm Stokke](https://timm.stokke.me) with [Claude](https://claude.ai), after two years of being annoyed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t1mmen/srtd",
-  "version": "0.0.0-next-20251227013823",
+  "version": "0.0.0-next-20251227065529",
   "license": "MIT",
   "description": "Supabase Repeatable Template Definitions (srtd): 🪄 Live-reloading SQL templates for Supabase DX. Make your database changes reviewable and migrations maintainable! 🚀",
   "bin": {