supatool 0.1.23 → 0.3.1

package/README.md

@@ -2,6 +2,7 @@
 
 A CLI tool that automatically generates TypeScript CRUD code from Supabase type definitions.
 
+
 ## Install
 
 ```
@@ -14,36 +15,88 @@ pnpm add -g supatool
 
 ## Usage
 
-1. Generate Supabase type definition file
+### 1. Extract Database Schema (NEW in v0.3.0)
+
+Extract and categorize all database objects from your Supabase project:
+
+```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:**
 ```
-npx supabase gen types typescript --project-id your_project_ref --schema public > shared/types.ts
+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
 ```
 
-2. Auto-generate CRUD code
+### 2. Generate CRUD Code
 
-```
+Generate TypeScript CRUD functions from Supabase types:
+
+```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/`
 
-3. Subcommands
+**Output:** `src/integrations/supabase/crud-autogen/`
 
-For more extensible usage, execute with subcommands:
+### 3. 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
+```
 
-- Show help text for all commands:
-  ```sh
-  supatool help
-  ```
+**Supported environment variables:**
+- `SUPABASE_CONNECTION_STRING` (preferred)
+- `DATABASE_URL` (fallback)
+- `SUPATOOL_MAX_CONCURRENT` (max concurrent table processing, default: 20, max: 50)
 
-- Specify input and output folder:
-  ```sh
-  supatool -i path/to/type -o path/to/export
-  ```
+### 4. Additional Commands
 
-For detailed usage, see:
-- [src/bin/helptext.ts](./src/bin/helptext.ts) (for development)
-- [dist/bin/helptext.js](./dist/bin/helptext.js) (for npm package)
+```bash
+# Show help for all commands
+supatool help
+
+# Specify custom input/output paths
+supatool crud -i path/to/types -o path/to/output
+```
 
 ## Note: Supabase Client Requirement
 
@@ -56,22 +109,41 @@ import { createClient } from '@supabase/supabase-js'
 export const supabase = createClient('YOUR_SUPABASE_URL', 'YOUR_SUPABASE_ANON_KEY')
 ```
 
-## VSCode/Cursor: Run Supabase CLI and supatool together
+## VSCode/Cursor Integration
 
-You can add a task to `.vscode/tasks.json` to run both commands at once:
+Add these tasks to `.vscode/tasks.json` for quick access:
 
-> **Note:**
-> After installing supatool, please restart VSCode (or your terminal) before using the task, so that the new command is recognized.
+> **Note:** Restart VSCode/Cursor after installing supatool to ensure the command is recognized.
 
 ```json
 {
   "version": "2.0.0",
   "tasks": [
     {
-      "label": "Generate Supabase types and CRUD",
+      "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": "mkdir -p shared && npx supabase gen types typescript --project-id your_project_id --schema public > shared/types.ts && supatool crud --force",
+      "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"
     }
   ]
 }
@@ -84,7 +156,7 @@ CRUD utility files for the `apps` table will be generated in `src/integrations/s
 You can import and use these functions in your application as follows:
 
 ```ts
-// Example: Using CRUD functions for the apps table
+// Example: Using CRUD functions for the apps table (v0.3.0+)
 import {
   selectAppsRowsWithFilters,
   selectAppsSingleRowWithFilters,
@@ -94,23 +166,26 @@ import {
   deleteAppsRow,
 } from 'src/integrations/supabase/crud-autogen/apps';
 
-// Get multiple rows with filters
-const apps = await selectAppsRowsWithFilters({ status: 'active' });
+// Select multiple rows with filters (NEW: destructuring parameters)
+const apps = await selectAppsRowsWithFilters({ filters: { status: 'active' } });
 
-// Get a single row with filters
-const app = await selectAppsSingleRowWithFilters({ id: 'your-app-id' });
+// Select a single row with filters
+const app = await selectAppsSingleRowWithFilters({ filters: { id: 'your-app-id' } });
 
-// Get by ID
-const appById = await selectAppsRowById('your-app-id');
+// Select by ID (NEW: destructuring parameters)
+const appById = await selectAppsRowById({ id: 'your-app-id' });
 
-// Create new row
-const newApp = await insertAppsRow({ name: 'New App', status: 'active' });
+// Insert new row (NEW: destructuring parameters)
+const newApp = await insertAppsRow({ data: { name: 'New App', status: 'active' } });
 
-// Update row
-const updatedApp = await updateAppsRow({ id: 'your-app-id', name: 'Updated Name' });
+// Update row (NEW: destructuring parameters)
+const updatedApp = await updateAppsRow({ 
+  id: 'your-app-id', 
+  data: { name: 'Updated Name' } 
+});
 
-// Delete row
-const deletedApp = await deleteAppsRow('your-app-id');
+// Delete row (NEW: destructuring parameters)
+const success = await deleteAppsRow({ id: 'your-app-id' });
 ```
 
 - All functions are async and return the corresponding row type.
@@ -128,4 +203,151 @@ For more details, see the project on GitHub: [https://github.com/idea-garage/sup
 
 ## Acknowledgements
 
-This project is inspired by and made possible thanks to the amazing work of [Supabase](https://supabase.com/).
+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
+```
+
+### Model-First Development
+
+Start from YAML model definitions:
+
+```bash
+# 1. Create model definition
+supatool create model.yaml
+
+# 2. Generate everything from model
+supatool gen:all model.yaml
+```
+
+### Extract Command Options
+
+Extract database objects in Supabase declarative schema format:
+
+```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
+```
+
+## New Features (v0.3.0)
+
+- **🔍 Schema Extraction**: Extract and categorize all database objects (tables, views, RLS, functions, triggers)
+- **📋 Supabase Declarative Schema**: Fully compliant with [Supabase's declarative database schemas](https://supabase.com/docs/guides/local-development/declarative-database-schemas) workflow
+- **🤖 AI-Friendly Index**: Auto-generated index.md and llms.txt files for better AI understanding of schema structure  
+- **💬 Comment Support**: Automatically extracts and includes database comments in generated files
+- **📁 Organized Output**: Separate directories for different object types with flexible organization options
+- **🎯 Pattern Matching**: Extract specific tables/views using wildcard patterns
+- **👁️ View Support**: Enhanced CRUD generation with SELECT-only operations for database views
+- **⚛️ React Query Integration**: Generate modern React hooks for data fetching
+- **🔧 Flexible Workflows**: Support both database-first and model-first development approaches
+
+## Changelog
+
+## Database Comments
+
+Supatool automatically extracts and includes PostgreSQL comments in all generated files. Comments enhance documentation and AI understanding of your schema.
+
+### Adding Comments to Your Database
+
+```sql
+-- Table comments
+COMMENT ON TABLE users IS 'User account information and authentication data';
+
+-- View comments
+COMMENT ON VIEW user_profiles IS 'Combined user data with profile information';
+
+-- Function comments
+COMMENT ON FUNCTION update_timestamp() IS 'Automatically updates the updated_at column';
+
+-- Custom type comments
+COMMENT ON TYPE user_status IS 'Enumeration of possible user account statuses';
+```
+
+### Comment Integration
+
+Comments appear in:
+- **index.md**: Human-readable file listings with descriptions (tables/views only)
+- **llms.txt**: AI-friendly format (`type:name:path:comment`)
+- **Generated SQL**: As `COMMENT ON` statements for full schema recreation
+
+**Example output:**
+```markdown
+## Tables
+- [users](tables/users.sql) - User account information and authentication data
+- [posts](tables/posts.sql) - User-generated content and blog posts
+```
+
+## Changelog
+
+### v0.3.0
+
+**NEW Features:**
+- **NEW**: `extract` command for database schema extraction
+- **NEW**: Full compliance with Supabase declarative database schemas workflow
+- **NEW**: AI-friendly index.md and llms.txt generation for better schema understanding
+- **NEW**: Database comment extraction and integration
+- **NEW**: Organized directory structure (tables/, views/, rls/, rpc/)
+- **NEW**: Pattern matching for selective extraction
+- **ENHANCED**: Support for all database object types (RLS, functions, triggers, cron jobs, custom types)
+- **ENHANCED**: Flexible output options with --no-separate compatibility
+
+**Enhanced Error Handling:**
+- Comprehensive try-catch blocks for all CRUD operations
+- Enhanced null/undefined checks with proper fallbacks
+- Detailed error messages with contextual information
+- Special handling for PGRST116 errors (record not found)
+- Parameter validation for required fields
+- Proper error logging and debugging support
+
+**Breaking Changes:**
+- **Function Parameter Format**: All CRUD functions now use destructuring assignment
+  - Before: `selectTableRowById(id: string)`
+  - After: `selectTableRowById({ id }: { id: string })`
+- **Type Safety**: Enhanced TypeScript type annotations for all functions
+
+### v0.2.0
+- Added `gen:` commands for code and schema generation
+- Enhanced `create` command  
+- Introduced model schema support (`schemas/supatool-data.schema.ts`)

package/dist/bin/helptext.js

@@ -1,36 +1,122 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.helpText = void 0;
+exports.modelSchemaHelp = exports.helpText = void 0;
 // See: [src/bin/helptext.ts](./src/bin/helptext.ts) from project root
 // Help text (command section from README, English only)
 exports.helpText = `
-Supatool CLI - Generate TypeScript CRUD code from Supabase type definitions
+Supatool CLI - Supabase database schema extraction and TypeScript CRUD generation
 
 Usage:
-  supatool crud [options]
-  supatool help
+  supatool <command> [options]
 
 Commands:
-  crud    Generate CRUD code
-  help    Show help
+  extract            Extract and categorize database objects from Supabase
+  gen:schema-crud    Generate CRUD code from supabase/schemas SQL files
+  crud               Generate CRUD code from Supabase type definitions
+  gen:types          Generate TypeScript types from model YAML
+  gen:crud           Generate CRUD TypeScript code from model YAML
+  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
+  config:init        Generate configuration template
+  help               Show help
 
-Options:
-  -i, --import <path>   Import path for type definitions (default: shared/)
-  -e, --export <path>   Output path for CRUD code (default: src/integrations/supabase/)
-  -t, --tables <names>  Generate code for specific tables only (comma separated, e.g. table1,table2)
-  -f, --force           Overwrite output folder without confirmation
-  -h, --help            Show help
-  -V, --version         Show version
+Extract Options:
+  -c, --connection <string>    Supabase connection string
+  -o, --output-dir <path>      Output directory (default: ./supabase/schemas)
+  -t, --tables <pattern>       Table pattern with wildcards (default: *)
+  --tables-only                Extract only table definitions
+  --views-only                 Extract only view definitions
+  --all                        Extract all DB objects (tables, views, RLS, functions, triggers, cron, types)
+  --no-separate                Output all objects in same directory
+  --schema <schemas>           Target schemas, comma-separated (default: public)
 
 Examples:
+  # Set connection in .env.local (recommended)
+  echo "SUPABASE_CONNECTION_STRING=postgresql://..." >> .env.local
+  
+  # Extract all database objects with AI-friendly index
+  supatool extract --all -o supabase/schemas
+  # Output:
+  #   supabase/schemas/index.md (Human-readable index with table/view comments)
+  #   supabase/schemas/llms.txt (AI-friendly structured data with comments)
+  #   supabase/schemas/tables/*.sql (Tables with comments)
+  #   supabase/schemas/views/*.sql (Views with comments)
+  #   supabase/schemas/rls/*.sql (RLS policies)
+  #   supabase/schemas/rpc/*.sql (Functions & triggers)
+  #   supabase/schemas/cron/*.sql (Cron jobs)
+  #   supabase/schemas/types/*.sql (Custom types)
+
+  # Extract only tables and views (default)
+  supatool extract -o supabase/schemas
+
+  # Extract to single directory (legacy mode)
+  supatool extract --no-separate -o supabase/schemas
+
+  # Extract specific pattern
+  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
+
+  # Complete database-first workflow
+  echo "SUPABASE_CONNECTION_STRING=postgresql://..." >> .env.local
+  supatool extract --all -o supabase/schemas
+  supatool gen:schema-crud --include-views --react-query
+
+  # Model-first workflow
+  supatool create model.yaml
+  supatool gen:all model.yaml
+
+  # Legacy CRUD generation
   supatool crud
-    - Import path: shared/
-    - Export path: src/integrations/supabase/
 
-  supatool crud -i path/to/import -e path/to/export
-    - Import path: path/to/import
-    - Export path: path/to/export
+Database Comments:
+  Supatool automatically extracts and includes database comments in generated files.
+  
+  To add comments to your database objects:
+  
+  # Table comments
+  COMMENT ON TABLE users IS 'User account information';eha,
+  
+  # View comments
+  COMMENT ON VIEW user_profiles IS 'Combined user data with profile information';
+  
+  # Function comments
+  COMMENT ON FUNCTION update_timestamp() IS 'Automatically updates the updated_at column';
+  
+  # Custom type comments
+  COMMENT ON TYPE user_status IS 'Enumeration of possible user account statuses';
+  
+  Comments will appear in:
+  - index.md: Human-readable list with descriptions (tables/views only)
+  - llms.txt: AI-friendly format (type:name:path:comment)
+  - Generated SQL files: As COMMENT statements
+`;
+// Model Schema Usage
+exports.modelSchemaHelp = `
+Model Schema Usage (schemas/supatool-data.schema.ts):
+
+- Import in TypeScript:
+  import { SUPATOOL_MODEL_SCHEMA } from 'supatool/schemas/supatool-data.schema';
+
+- Validate with ajv:
+  import Ajv from 'ajv';
+  const ajv = new Ajv();
+  const validate = ajv.compile(SUPATOOL_MODEL_SCHEMA);
+  const data = /* your YAML/JSON parsed object */;
+  if (!validate(data)) {
+    console.error(validate.errors);
+  } else {
+    console.log('Valid!');
+  }
 
-  supatool crud -t users,posts
-    - Only generate for users and posts tables
+- Use with AI:
+  const schemaJson = JSON.stringify(SUPATOOL_MODEL_SCHEMA, null, 2);
+  // Pass schemaJson to your AI prompt or API
 `;