supatool 0.3.6 → 0.4.0

package/README.md

@@ -1,330 +1,97 @@
 # Supatool
 
-A CLI tool that automatically generates TypeScript CRUD code from Supabase type definitions.
+CLI for Supabase: **extract** schema to files with **llms.txt** for LLMs, and **seed** export as AI-friendly JSON. Deploy and CRUD (deprecated) also available.
 
 ## Features
-- Extract and categorize all database objects (tables, views, RLS, functions, triggers) from Supabase
-- Generate TypeScript CRUD functions from Supabase types or model YAML
-- Output human-readable and AI-friendly schema/index files
-- Flexible environment/configuration and batch processing
-- Simple CLI with help and documentation
 
-> For all new features and version history, see [CHANGELOG.md](./CHANGELOG.md).
+- **Extract** – Tables, views, RLS, functions, triggers from DB into files. One file per table (DDL + RLS + triggers). Multi-schema: `--schema public,agent` → `schemas/public/`, `schemas/agent/`.
+- **llms.txt** – Catalog with OBJECTS, RELATIONS, RPC_TABLES, ALL_SCHEMAS. README in output links to it.
+- **Seed** – Export table data to JSON; llms.txt index in `supabase/seeds/`.
+- **Deploy** – Push local schema to remote (`supatool deploy --dry-run`).
+- CRUD code gen is **deprecated** (`supatool crud`, `gen:crud`); prefer writing code with an LLM.
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history.
 
 ## Install
 
-```
+```bash
 npm install -g supatool
-# or
-yarn global add supatool
-# or
-pnpm add -g supatool
+# or: yarn global add supatool  |  pnpm add -g supatool
 ```
 
-## Usage
+## Extract
 
-### Extract Database Schema
-
-Extract and categorize all database objects from your Supabase project:
+Set connection (e.g. in `.env.local`):
 
 ```bash
-# Set connection string in environment (recommended)
 echo "SUPABASE_CONNECTION_STRING=postgresql://..." >> .env.local
-
-# Extract all database objects with AI-friendly index
-supatool extract --all -o supabase/schemas
-
-# Extract only tables and views
-supatool extract -o supabase/schemas
-
-# Extract specific tables with pattern
-supatool extract -t "user_*" -o supabase/schemas
-
-# Extract from specific schemas (comma-separated)
-supatool extract --all --schema public,auth,extensions -o supabase/schemas
-
-# Alternative: specify connection directly
-supatool extract --all -c "postgresql://..." -o supabase/schemas
-```
-
-**Output structure:**
-```
-supabase/schemas/
-├── index.md              # Human-readable index with comments
-├── llms.txt              # AI-friendly structured data with comments
-├── tables/               # Table definitions with comments
-├── views/                # View definitions with comments
-├── rls/                  # RLS policies
-└── rpc/                  # Functions & triggers
 ```
 
-### Generate CRUD Code
-
-Generate TypeScript CRUD functions from Supabase types:
+Extract all objects:
 
 ```bash
-# Generate from Supabase type definitions
-supatool crud
-
-# Generate from schema SQL files  
-supatool gen:schema-crud --include-views --react-query
-
-# Generate from model YAML
-supatool gen:crud model.yaml
-```
-
-**Output:** `src/integrations/supabase/crud-autogen/`
-
-### Environment Configuration
-
-For security and convenience, set your connection string in environment variables:
-
-```bash
-# Create .env.local file with your connection details
-cat > .env.local << EOF
-SUPABASE_CONNECTION_STRING=postgresql://user:password@host:port/database
-# Alternative: use DATABASE_URL
-DATABASE_URL=postgresql://user:password@host:port/database
-EOF
-
-# Now you can run commands without -c flag
 supatool extract --all -o supabase/schemas
+# Optional: --schema public,agent  |  -t "user_*"  |  -c "postgresql://..."
+# With --force: clears output dir then writes (no orphan files).
 ```
 
-**Supported environment variables:**
-- `SUPABASE_CONNECTION_STRING` (preferred)
-- `DATABASE_URL` (fallback)
-- `SUPATOOL_MAX_CONCURRENT` (max concurrent table processing, default: 20, max: 50)
-
-### Additional Commands
-
-```bash
-# Show help for all commands
-supatool help
-
-# Specify custom input/output paths
-supatool crud -i path/to/types -o path/to/output
-```
-
-## Database Comments
-
-Supatool automatically extracts and includes PostgreSQL comments in all generated files. Comments enhance documentation and AI understanding of your schema.
-
-- Table, view, function, and type comments are included in generated SQL and documentation.
-- AI-friendly index files (llms.txt) and Markdown index (index.md) include comments for better context.
-
-## VSCode/Cursor Integration
-
-Add these tasks to `.vscode/tasks.json` for quick access:
-
-> **Note:** Restart VSCode/Cursor after installing supatool to ensure the command is recognized.
-
-```json
-{
-  "version": "2.0.0",
-  "tasks": [
-    {
-      "label": "Extract Schema and Generate CRUD",
-      "type": "shell",
-      "command": "supatool extract --all -o supabase/schemas && supatool gen:schema-crud --react-query",
-      "group": "build",
-      "dependsOn": "setup-env"
-    },
-    {
-      "label": "setup-env",
-      "type": "shell",
-      "command": "echo 'Ensure SUPABASE_CONNECTION_STRING is set in .env.local'",
-      "group": "build"
-    },
-    {
-      "label": "Generate Types and CRUD (Legacy)",
-      "type": "shell", 
-      "command": "mkdir -p shared && npx supabase gen types typescript --project-id ${input:projectId} --schema public > shared/types.ts && supatool crud --force",
-      "group": "build"
-    }
-  ],
-  "inputs": [
-    {
-      "id": "projectId", 
-      "description": "Supabase project ID",
-      "default": "your_project_id"
-    }
-  ]
-}
-```
-
-## Example: How to use generated CRUD code in your apps
-
-CRUD utility files for the `apps` table will be generated in `src/integrations/supabase/crud-autogen/` by default.
-
-You can import and use these functions in your application as follows:
-
-```ts
-// Example: Using CRUD functions for the apps table (v0.3.0+)
-import {
-  selectAppsRowsWithFilters,
-  selectAppsSingleRowWithFilters,
-  selectAppsRowById,
-  insertAppsRow,
-  updateAppsRow,
-  deleteAppsRow,
-} from 'src/integrations/supabase/crud-autogen/apps';
-
-// Select multiple rows with filters (NEW: destructuring parameters)
-const apps = await selectAppsRowsWithFilters({ filters: { status: 'active' } });
-
-// Select a single row with filters
-const app = await selectAppsSingleRowWithFilters({ filters: { id: 'your-app-id' } });
+**Output:**
 
-// Select by ID (NEW: destructuring parameters)
-const appById = await selectAppsRowById({ id: 'your-app-id' });
-
-// Insert new row (NEW: destructuring parameters)
-const newApp = await insertAppsRow({ data: { name: 'New App', status: 'active' } });
-
-// Update row (NEW: destructuring parameters)
-const updatedApp = await updateAppsRow({ 
-  id: 'your-app-id', 
-  data: { name: 'Updated Name' } 
-});
-
-// Delete row (NEW: destructuring parameters)
-const success = await deleteAppsRow({ id: 'your-app-id' });
 ```
-
-- All functions are async and return the corresponding row type.
-- You can use filter objects for flexible queries.
-- See the generated file for each table in `src/integrations/supabase/crud-autogen/` for details.
-
-## Limitations
-
-Currently, the generated code only supports tables where the primary key column is named `id`.
-If your table's primary key is not named `id`, the `selectById`, `update`, and `delete` functions will not be generated for that table.
-
-## Repository
-
-For more details, see the project on GitHub: [https://github.com/idea-garage/supatool](https://github.com/idea-garage/supatool)
-
-## Acknowledgements
-
-This project is inspired by and made possible thanks to the amazing work of [Supabase](https://supabase.com/).
-
-## Complete Workflow Examples
-
-### Database-First Development
-
-Extract your existing database schema and generate CRUD code using [Supabase's declarative schema workflow](https://supabase.com/docs/guides/local-development/declarative-database-schemas):
-
-```bash
-# 1. Set connection string in .env.local
-echo "SUPABASE_CONNECTION_STRING=postgresql://..." >> .env.local
-
-# 2. Extract all database objects to supabase/schemas (declarative schema format)
-supatool extract --all -o supabase/schemas
-
-# 3. Generate migrations from declarative schema
-supabase db diff -f initial_schema
-
-# 4. Generate TypeScript types with Supabase CLI  
-npx supabase gen types typescript --local > src/types/database.ts
-
-# 5. Generate CRUD functions with React Query support
-supatool gen:schema-crud --include-views --react-query
+supabase/schemas/
+├── README.md         # Points to llms.txt
+├── llms.txt          # OBJECTS, RELATIONS, RPC_TABLES, ALL_SCHEMAS (read this first for AI)
+├── schema_index.json # Same as llms.txt, for agents that parse JSON
+├── schema_summary.md # One-file overview: tables, relations, RPCs
+├── tables/
+├── views/
+├── rpc/
+├── cron/
+└── types/
 ```
 
-### Model-First Development
-
-Start from YAML model definitions:
-
-```bash
-# 1. Create model definition
-supatool create model.yaml
+Multi-schema: `schemas/public/`, `schemas/agent/`, etc., each with tables/, views/, rpc/.
 
-# 2. Generate everything from model
-supatool gen:all model.yaml
-```
+**Env:** `SUPABASE_CONNECTION_STRING` or `DATABASE_URL`; optional `SUPATOOL_MAX_CONCURRENT` (default 20).
 
-### Extract Command Options
+## Seed
 
-Extract database objects in Supabase declarative schema format:
+Export selected tables as JSON for AI/reference:
 
 ```bash
-# Recommended: Set connection in .env.local first
-echo "SUPABASE_CONNECTION_STRING=postgresql://..." >> .env.local
-
-# Extract all database objects to categorized directories (recommended)
-supatool extract --all -o supabase/schemas
-# Output: supabase/schemas/{index.md,tables/,views/,rls/,rpc/}
-# Compatible with: supabase db diff
-
-# Extract only tables and views
-supatool extract -o supabase/schemas  
-# Output: supabase/schemas/{index.md,tables/,views/}
-
-# Extract to single directory (for simple projects)
-supatool extract --no-separate -o supabase/schemas
-# Output: supabase/schemas/{index.md,*.sql}
-
-# Extract with pattern matching
-supatool extract -t "user_*" -o ./user-tables
-
-# Extract from specific schemas (default: public)
-supatool extract --all --schema public,auth,extensions -o supabase/schemas
-
-# Alternative: specify connection directly
-supatool extract --all -c "postgresql://..." -o supabase/schemas
+supatool seed --tables tables.yaml --connection "postgresql://..."
 ```
 
-## Seed Command (v0.3.5+)
-
-Export selected table data from your remote Supabase DB as AI-friendly seed JSON files.
+`tables.yaml`:
 
-### Usage
-
-```
-supatool seed --tables tables.yaml --connection <CONNECTION_STRING>
+```yaml
+tables:
+  - users
+  - public.orders
 ```
 
-- `tables.yaml` example:
-  ```yaml
-  tables:
-    - users
-    - public.orders
-  ```
 - Output: `supabase/seeds/<timestamp>_supatool/{table}_seed.json`
-- Each file contains a snapshot of the remote DB table at the time of export.
+- `llms.txt` is written in `supabase/seeds/` listing files and row counts.
 
-### Example output (users_seed.json)
-```json
-{
-  "table": "public.users",
-  "fetched_at": "2024-07-05T11:16:00Z",
-  "fetched_by": "supatool v0.3.5",
-  "note": "This data is a snapshot of the remote DB at the above time. For AI coding reference. You can update it by running the update command again.",
-  "rows": [
-    { "id": 1, "name": "Taro Yamada", "email": "taro@example.com" },
-    { "id": 2, "name": "Hanako Suzuki", "email": "hanako@example.com" }
-  ]
-}
-```
+Do not include sensitive data in seed files.
 
-> **Warning:** Do not include sensitive or personal data in seed files. Handle all exported data with care.
+## For AI / coding agents (Claude CLI, Cursor, etc.)
 
-### llms.txt (AI seed data index)
+- **Entry point:** Read `supabase/schemas/llms.txt` first. It lists all objects, relations, RPC→tables, and schemas.
+- **Then** open only the files you need (paths under OBJECTS). Use RELATIONS for joins; RPC_TABLES to see which RPCs touch which tables.
+- **Optional:** `schema_index.json` (same data as llms.txt) and `schema_summary.md` (one-file overview) are written when you run `supatool extract`.
+- **Seeds:** `supabase/seeds/llms.txt` lists seed JSON files; it references the schema catalog at `../schemas/llms.txt` when present.
 
-After exporting, a file named `llms.txt` is automatically generated (and overwritten) in the `supabase/seeds/` directory. This file lists all seed JSON files in the latest timestamped folder, with table name, fetch time, and row count for AI reference.
+## Other commands
 
-- Note: `llms.txt` is not generated inside each timestamped subfolder, only in `supabase/seeds/`.
+- `supatool help` – List commands
+- `supatool deploy --dry-run` – Preview deploy
+- CRUD: `supatool crud`, `gen:crud` (deprecated)
 
-#### Example llms.txt
-```
-# AI seed data index (generated by supatool)
-# fetched_at: 2024-07-05T11:16:00Z
-# folder: 20240705_1116_supatool
-public.users: users_seed.json (2 rows) # User account table
-public.orders: orders_seed.json (5 rows)
-```
+## Repository
+
+[https://github.com/idea-garage/supatool](https://github.com/idea-garage/supatool) · [npm](https://www.npmjs.com/package/supatool)
 
-## More Information
+---
 
-For full version history and detailed changes, see [CHANGELOG.md](./CHANGELOG.md).
+Acknowledgements: Development would not be this convenient without [Supabase](https://supabase.com/). Thanks to the team and the platform.

package/dist/bin/helptext.js

@@ -12,14 +12,15 @@ Usage:
 Commands:
   extract            Extract database objects from Supabase
   gen:types          Generate TypeScript types from model YAML
-  gen:crud           Generate CRUD TypeScript code from model YAML
+  gen:crud           Generate CRUD TypeScript code from model YAML [deprecated - prefer writing code with LLM]
   gen:docs           Generate Markdown documentation from model YAML
   gen:sql            Generate SQL (tables, relations, RLS/security) from model YAML
   gen:rls            Generate RLS/security SQL from model YAML
   gen:all            Generate all outputs from model YAML
   create             Generate a template model YAML
-  crud               Generate CRUD code from Supabase type definitions
-  sync               Sync local and remote schemas
+  crud               Generate CRUD code from Supabase type definitions [deprecated - prefer writing code with LLM]
+  deploy             Deploy local schema changes to remote (recommended)
+  sync               Sync local and remote schemas [deprecated - use deploy]
   seed               Export selected table data as AI-friendly seed JSON
   config:init        Generate configuration template
   help               Show help