Initial commit

commands/convert-project.md

@@ -0,0 +1,64 @@
+Convert asyncpg FastAPI project to SQLAlchemy async patterns
+
+This command analyzes a FastAPI project, detects all asyncpg usage patterns, and systematically converts them to SQLAlchemy 2.0+ with async support while maintaining full functionality.
+
+## Usage
+
+```bash
+/convert-asyncpg-to-sqlalchemy [options]
+```
+
+## Options
+
+- `--path <directory>`: Project directory to analyze (default: current directory)
+- `--backup <directory>`: Backup location before conversion (default: ./backup_asyncpg)
+- `--supabase`: Enable Supabase-specific optimizations and integrations
+- `--models-only`: Only convert models, skip utility functions
+- `--dry-run`: Preview changes without modifying files
+- `--interactive`: Prompt for confirmation on major changes
+
+## Process
+
+### Phase 1: Detection & Analysis
+1. Scan all Python files for asyncpg imports and usage patterns
+2. Analyze connection methods, query patterns, and transaction handling
+3. Generate detailed conversion report with complexity assessment
+
+### Phase 2: Backup Creation
+1. Create complete backup of original code
+2. Generate conversion log for rollback capabilities
+3. Document all detected patterns and planned changes
+
+### Phase 3: Systematic Conversion
+1. Update imports from asyncpg to SQLAlchemy
+2. Convert connection patterns to async session management
+3. Transform query syntax (fetch → execute, parameter binding)
+4. Update transaction handling patterns
+5. Convert error handling to SQLAlchemy exceptions
+
+### Phase 4: Validation
+1. Syntax validation of converted code
+2. Import verification and dependency checking
+3. Basic functionality testing of converted patterns
+
+### Phase 5: Documentation
+1. Generate conversion summary report
+2. Create migration guide with before/after examples
+3. Document any manual intervention requirements
+
+## Examples
+
+Convert current directory with Supabase support:
+```bash
+/convert-asyncpg-to-sqlalchemy --supabase
+```
+
+Dry run to preview changes:
+```bash
+/convert-asyncpg-to-sqlalchemy --dry-run --path ./my-fastapi-app
+```
+
+Interactive conversion with custom backup:
+```bash
+/convert-asyncpg-to-sqlalchemy --path ./src --backup ./original_code --interactive
+```

commands/create-session.md

@@ -0,0 +1,92 @@
+Create SQLAlchemy async session management setup
+
+This command generates complete async session management configuration for FastAPI projects, including dependency injection, connection pooling, error handling, and Supabase integration patterns.
+
+## Usage
+
+```bash
+/create-async-session [options]
+```
+
+## Options
+
+- `--output <directory>`: Output directory for session files (default: ./database)
+- `--supabase`: Include Supabase-specific configurations
+- `--pool-size <number>`: Connection pool size (default: 10)
+- `--max-overflow <number>`: Maximum overflow connections (default: 0)
+- `--testing`: Include testing configuration and fixtures
+- `--migrations`: Include Alembic migration setup
+- `--docker`: Generate Docker Compose configuration
+
+## Generated Components
+
+### Core Session Management
+- Async engine configuration with proper connection pooling
+- Async session factory setup
+- FastAPI dependency injection patterns
+- Connection lifecycle management
+
+### Database Configuration
+- Environment-based configuration management
+- Connection string handling with security
+- Pool optimization for different deployment targets
+- Serverless environment optimizations
+
+### Error Handling & Monitoring
+- Database error handling patterns
+- Connection retry logic with exponential backoff
+- Health check endpoints for database connectivity
+- Logging and monitoring setup
+
+### Testing Support
+- In-memory database configuration for testing
+- Test fixtures and utilities
+- Transaction rollback testing patterns
+- Mock session providers
+
+### Supabase Integration (optional)
+- Supabase auth integration with RLS
+- Service key management
+- Row Level Security context handling
+- Supabase-specific connection optimizations
+
+## Examples
+
+Create basic session setup:
+```bash
+/create-async-session --output ./src/database
+```
+
+Create Supabase-enabled session management:
+```bash
+/create-async-session --supabase --pool-size 20 --testing
+```
+
+Complete setup with migrations and Docker:
+```bash
+/create-async-session --testing --migrations --docker --supabase
+```
+
+## Generated Files
+
+### Core Files
+- `database.py` - Main database configuration and session factory
+- `dependencies.py` - FastAPI dependency injection patterns
+- `config.py` - Environment-based configuration management
+- `exceptions.py` - Custom database exception handlers
+
+### Optional Files
+- `testing.py` - Testing configuration and fixtures
+- `migrations/` - Alembic migration setup
+- `docker-compose.yml` - Database container configuration
+- `supabase_integration.py` - Supabase-specific integration patterns
+
+### Features
+- Async session management with proper cleanup
+- Connection pooling optimized for different environments
+- Error handling with retry mechanisms
+- Testing utilities with in-memory database support
+- Supabase auth and RLS integration
+- Health check endpoints and monitoring
+- Docker development environment setup
+- Comprehensive logging and debugging support

commands/generate-models.md

@@ -0,0 +1,78 @@
+Generate SQLAlchemy models from database schema
+
+This command connects to your database (PostgreSQL/Supabase), reflects the schema structure, and generates complete SQLAlchemy model definitions with proper relationships, constraints, and type mappings.
+
+## Usage
+
+```bash
+/generate-sqlalchemy-models [options]
+```
+
+## Options
+
+- `--url <connection_string>`: Database connection string (or uses SUPABASE_URL env var)
+- `--schema <name>`: Schema to reflect (default: public)
+- `--output <file>`: Output file for generated models (default: models.py)
+- `--base-class <name>`: Base class for all models (default: Base)
+- `--lazy-load`: Enable lazy loading for large schemas
+- `--include-extensions`: Include table relationships from database extensions
+- `--supabase-optimize`: Optimize for Supabase-specific features (RLS, UUIDs, etc.)
+
+## Schema Reflection Features
+
+### Automatic Type Detection
+- Maps PostgreSQL types to SQLAlchemy types
+- Handles Supabase-specific types (uuid_generate_v4(), jsonb, timestamptz)
+- Detects auto-incrementing primary keys and sequences
+
+### Relationship Generation
+- Automatically detects foreign key constraints
+- Creates bi-directional relationships with proper back_populates
+- Handles many-to-many relationships through junction tables
+
+### Constraint Mapping
+- Primary key constraints (composite keys supported)
+- Unique constraints and indexes
+- Check constraints and default values
+- NOT NULL constraints and nullable columns
+
+### Supabase Integration
+- Row Level Security (RLS) policy hints
+- Supabase auth user table relationships
+- Storage bucket integration patterns
+- Webhook table handling
+
+## Examples
+
+Generate models from Supabase:
+```bash
+/generate-sqlalchemy-models --url "postgresql+asyncpg://user:pass@host:5432/db" --supabase-optimize
+```
+
+Generate for specific schema with lazy loading:
+```bash
+/generate-sqlalchemy-models --schema analytics --output analytics_models.py --lazy-load
+```
+
+Reflect all schemas with extensions:
+```bash
+/generate-sqlalchemy-models --include-extensions --base-class CustomBase
+```
+
+## Output Format
+
+The command generates:
+- SQLAlchemy model classes with proper type hints
+- Column definitions with constraints and defaults
+- Relationship definitions with cascade options
+- Import statements and base class definition
+- Optional migration script for existing code
+
+## Generated Features
+
+- Type hints for all columns and relationships
+- Proper __repr__ methods for debugging
+- Validation methods for common use cases
+- Supabase-specific optimizations
+- Lazy loading support for large schemas
+- JSON serialization methods for API responses

commands/validate-conversion.md

@@ -0,0 +1,140 @@
+Validate SQLAlchemy conversion and test functionality
+
+This command validates that the asyncpg to SQLAlchemy conversion was successful by running comprehensive tests, checking syntax validity, verifying database connectivity, and ensuring all functionality works as expected.
+
+## Usage
+
+```bash
+/validate-sqlalchemy-conversion [options]
+```
+
+## Options
+
+- `--path <directory>`: Project directory to validate (default: current directory)
+- `--connection-string <url>`: Database connection for testing (required)
+- `--test-data`: Run tests with sample data
+- `--performance`: Include performance benchmarks
+- `--supabase`: Include Supabase-specific validations
+- `--detailed`: Provide detailed validation report
+- `--fix-issues`: Attempt to automatically fix detected issues
+
+## Validation Categories
+
+### Syntax & Import Validation
+- Check all Python files for syntax errors
+- Verify SQLAlchemy imports are correct
+- Validate async/await usage patterns
+- Check for proper type hints and annotations
+
+### Database Connectivity
+- Test database connection establishment
+- Verify async session creation and cleanup
+- Test connection pooling functionality
+- Validate connection string parsing
+
+### Query Functionality Tests
+- Test basic CRUD operations (Create, Read, Update, Delete)
+- Validate parameter binding and escaping
+- Test complex queries with joins and aggregations
+- Verify transaction handling and rollback scenarios
+
+### Performance Benchmarks
+- Compare query performance between original and converted code
+- Test connection pooling efficiency
+- Memory usage analysis during database operations
+- Concurrent request handling validation
+
+### Supabase Integration Tests (optional)
+- Row Level Security (RLS) functionality
+- JWT token validation with database sessions
+- Supabase auth integration testing
+- Storage integration with database operations
+
+## Validation Process
+
+### Phase 1: Static Analysis
+1. Syntax validation of all Python files
+2. Import verification and dependency checking
+3. Async pattern validation and coroutine checking
+4. Type hint verification for better IDE support
+
+### Phase 2: Database Testing
+1. Connection establishment tests
+2. Session lifecycle validation
+3. Basic CRUD operation testing
+4. Error handling and recovery testing
+
+### Phase 3: Integration Testing
+1. FastAPI endpoint testing with database operations
+2. Dependency injection validation
+3. Concurrent request handling
+4. Memory leak detection
+
+### Phase 4: Performance Analysis
+1. Query execution time comparison
+2. Connection pool efficiency testing
+3. Memory usage profiling
+4. Scalability assessment
+
+## Examples
+
+Basic validation:
+```bash
+/validate-sqlalchemy-conversion --connection-string "postgresql+asyncpg://user:pass@host:5432/db"
+```
+
+Comprehensive validation with Supabase support:
+```bash
+/validate-sqlalchemy-conversion --supabase --performance --test-data --detailed
+```
+
+Validate specific directory with auto-fix:
+```bash
+/validate-sqlalchemy-conversion --path ./src/api --connection-string $DATABASE_URL --fix-issues
+```
+
+## Output Reports
+
+### Summary Report
+- Overall validation status (PASS/FAIL/WARNING)
+- Number of issues found and fixed
+- Performance metrics comparison
+- Recommendations for improvements
+
+### Detailed Issues Report
+- File-by-file validation results
+- Specific syntax errors and fixes applied
+- Missing imports or incorrect patterns
+- Performance bottlenecks identified
+
+### Performance Analysis
+- Query execution time comparisons
+- Connection pool efficiency metrics
+- Memory usage patterns
+- Scalability test results
+
+### Recommendations
+- Code improvement suggestions
+- Performance optimization opportunities
+- Security considerations
+- Best practice recommendations
+
+## Auto-Fix Capabilities
+
+When `--fix-issues` is enabled, the command can automatically:
+
+- Fix common import errors and missing dependencies
+- Correct async/await usage patterns
+- Update type hints for better IDE support
+- Fix basic syntax errors
+- Optimize connection pooling configurations
+- Update error handling patterns
+- Fix parameter binding issues
+- Correct transaction handling patterns
+
+## Exit Codes
+
+- `0`: Validation successful - all tests passed
+- `1`: Validation failed - critical issues found
+- `2`: Validation failed with warnings - non-critical issues present
+- `3`: Validation error - unable to complete validation due to environment issues