wegho-agentes 7.0.3 → 7.0.6

package/.agent/skills/database-design/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: database-design
+description: Database design, data modeling, governance, and query-organization skill. Use for schema design, indexing, migrations, relational modeling, SQL quality, metadata organization, data lineage thinking, dbt-style modeling, and governance-oriented data structure decisions.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Database Design
+
+> **Learn to THINK, not copy SQL patterns.**
+
+## 🎯 Selective Reading Rule
+
+**Read ONLY files relevant to the request!** Check the content map, find what you need.
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| `database-selection.md` | PostgreSQL vs Neon vs Turso vs SQLite | Choosing database |
+| `orm-selection.md` | Drizzle vs Prisma vs Kysely | Choosing ORM |
+| `schema-design.md` | Normalization, PKs, relationships | Designing schema |
+| `indexing.md` | Index types, composite indexes | Performance tuning |
+| `optimization.md` | N+1, EXPLAIN ANALYZE | Query optimization |
+| `migrations.md` | Safe migrations, serverless DBs | Schema changes |
+| `github-benchmarks.md` | Current GitHub-aligned references for data organization | Governance, metadata, SQL quality |
+| `supabase-security-egress.md` | Supabase security, egress, and cost controls | Supabase/PostgreSQL systems |
+
+## GitHub benchmark sources
+
+Use these repositories as the main external benchmark for modern data organization:
+- `supabase/supabase`
+- `supabase/agent-skills`
+- `datahub-project/datahub`
+- `open-metadata/OpenMetadata`
+- `open-metadata/OpenMetadataStandards`
+- `dbt-labs/dbt-core`
+- `sqlfluff/sqlfluff`
+
+---
+
+## ⚠️ Core Principle
+
+- ASK user for database preferences when unclear
+- Choose database/ORM based on CONTEXT
+- Don't default to PostgreSQL for everything
+- Model data ownership, discoverability, and governance early
+- Treat metadata, lineage, and naming consistency as first-class design concerns
+
+---
+
+## Decision Checklist
+
+Before designing schema:
+
+- [ ] Asked user about database preference?
+- [ ] Chosen database for THIS context?
+- [ ] Considered deployment environment?
+- [ ] Planned index strategy?
+- [ ] Defined relationship types?
+- [ ] Defined ownership and naming conventions?
+- [ ] Considered lineage / downstream consumers?
+- [ ] Considered retention, privacy, and minimization rules?
+
+---
+
+## Anti-Patterns
+
+❌ Default to PostgreSQL for simple apps (SQLite may suffice)
+❌ Skip indexing
+❌ Use SELECT * in production
+❌ Store JSON when structured data is better
+❌ Ignore N+1 queries
+❌ Model tables without ownership, lifecycle, or retention thinking
+❌ Treat analytics/data-governance layers as an afterthought
+
+## Modern organization baseline
+
+When the task touches data organization, cover these layers:
+1. Operational schema quality
+2. Naming and ownership clarity
+3. Lineage and downstream impact
+4. Query linting and maintainability
+5. Governance, retention, and sensitive-data handling
+
+This aligns better with the direction seen in DataHub, OpenMetadata, dbt, and SQLFluff.
+
+## Repository-specific expectations
+
+For `wegho-agentes` and similar PHP + TS/TSX + Supabase/PostgreSQL systems:
+- Prefer explicit relational structure over unbounded JSON
+- Document RLS assumptions alongside table design
+- Minimize sensitive data storage and define retention clearly
+- Keep file/blob payloads out of Supabase when rules require external storage
+- Treat SQL readability and predictable naming as review criteria, not polish
+
+## Supabase security and traffic baseline
+
+When the task uses Supabase, treat these as default architecture rules:
+1. Enable RLS on every exposed table and review policy cost
+2. Keep `service_role` strictly server-side
+3. Select only needed columns and always paginate large lists
+4. Index filter columns, join keys, and columns referenced by RLS
+5. Prefer metadata + external file hosting over storing large files in Supabase
+6. Use CDN-friendly public delivery only for non-sensitive assets
+7. Monitor egress, top paths, and query volume before scaling compute

package/.agent/skills/database-design/database-selection.md

@@ -0,0 +1,43 @@
+# Database Selection (2025)
+
+> Choose database based on context, not default.
+
+## Decision Tree
+
+```
+What are your requirements?
+│
+├── Full relational features needed
+│   ├── Self-hosted → PostgreSQL
+│   └── Serverless → Neon, Supabase
+│
+├── Edge deployment / Ultra-low latency
+│   └── Turso (edge SQLite)
+│
+├── AI / Vector search
+│   └── PostgreSQL + pgvector
+│
+├── Simple / Embedded / Local
+│   └── SQLite
+│
+└── Global distribution
+    └── PlanetScale, CockroachDB, Turso
+```
+
+## Comparison
+
+| Database | Best For | Trade-offs |
+|----------|----------|------------|
+| **PostgreSQL** | Full features, complex queries | Needs hosting |
+| **Neon** | Serverless PG, branching | PG complexity |
+| **Turso** | Edge, low latency | SQLite limitations |
+| **SQLite** | Simple, embedded, local | Single-writer |
+| **PlanetScale** | MySQL, global scale | No foreign keys |
+
+## Questions to Ask
+
+1. What's the deployment environment?
+2. How complex are the queries?
+3. Is edge/serverless important?
+4. Vector search needed?
+5. Global distribution required?

package/.agent/skills/database-design/github-benchmarks.md

@@ -0,0 +1,35 @@
+# GitHub Benchmarks for Data Organization Skill
+
+Use these repositories as the benchmark for what strong data organization looks like today:
+
+## `supabase/supabase`
+- Official reference for RLS-first browser access, storage delivery, Edge Functions, and platform usage controls
+- Important benchmark when data modeling decisions affect egress, auth, storage, and operational cost
+
+## `supabase/agent-skills`
+- Good benchmark for Supabase-specific agent guidance around schema quality, RLS performance, and safe platform usage
+
+## `datahub-project/datahub`
+- Reference for metadata-driven discovery, governance, and observability
+- Strong mental model for ownership, lineage, and searchable context
+
+## `open-metadata/OpenMetadata`
+- Reference for trusted data context, cataloging, profiling, lineage, and governance
+- Useful when designing systems that need clearer metadata and business semantics
+
+## `open-metadata/OpenMetadataStandards`
+- Good benchmark for structured metadata contracts and interoperability
+
+## `dbt-labs/dbt-core`
+- Strong reference for model layering, testing culture, transformation discipline, and SQL-as-code workflow
+
+## `sqlfluff/sqlfluff`
+- Strong reference for SQL quality, style, linting, and maintainability
+
+Translate lessons from these projects into:
+- clearer schema boundaries
+- naming standards
+- ownership and lineage
+- maintainable SQL
+- governance-aware data structures
+- Supabase-aware egress and storage discipline

package/.agent/skills/database-design/indexing.md

@@ -0,0 +1,39 @@
+# Indexing Principles
+
+> When and how to create indexes effectively.
+
+## When to Create Indexes
+
+```
+Index these:
+├── Columns in WHERE clauses
+├── Columns in JOIN conditions
+├── Columns in ORDER BY
+├── Foreign key columns
+└── Unique constraints
+
+Don't over-index:
+├── Write-heavy tables (slower inserts)
+├── Low-cardinality columns
+├── Columns rarely queried
+```
+
+## Index Type Selection
+
+| Type | Use For |
+|------|---------|
+| **B-tree** | General purpose, equality & range |
+| **Hash** | Equality only, faster |
+| **GIN** | JSONB, arrays, full-text |
+| **GiST** | Geometric, range types |
+| **HNSW/IVFFlat** | Vector similarity (pgvector) |
+
+## Composite Index Principles
+
+```
+Order matters for composite indexes:
+├── Equality columns first
+├── Range columns last
+├── Most selective first
+└── Match query pattern
+```

package/.agent/skills/database-design/migrations.md

@@ -0,0 +1,48 @@
+# Migration Principles
+
+> Safe migration strategy for zero-downtime changes.
+
+## Safe Migration Strategy
+
+```
+For zero-downtime changes:
+│
+├── Adding column
+│   └── Add as nullable → backfill → add NOT NULL
+│
+├── Removing column
+│   └── Stop using → deploy → remove column
+│
+├── Adding index
+│   └── CREATE INDEX CONCURRENTLY (non-blocking)
+│
+└── Renaming column
+    └── Add new → migrate data → deploy → drop old
+```
+
+## Migration Philosophy
+
+- Never make breaking changes in one step
+- Test migrations on data copy first
+- Have rollback plan
+- Run in transaction when possible
+
+## Serverless Databases
+
+### Neon (Serverless PostgreSQL)
+
+| Feature | Benefit |
+|---------|---------|
+| Scale to zero | Cost savings |
+| Instant branching | Dev/preview |
+| Full PostgreSQL | Compatibility |
+| Autoscaling | Traffic handling |
+
+### Turso (Edge SQLite)
+
+| Feature | Benefit |
+|---------|---------|
+| Edge locations | Ultra-low latency |
+| SQLite compatible | Simple |
+| Generous free tier | Cost |
+| Global distribution | Performance |

package/.agent/skills/database-design/optimization.md

@@ -0,0 +1,36 @@
+# Query Optimization
+
+> N+1 problem, EXPLAIN ANALYZE, optimization priorities.
+
+## N+1 Problem
+
+```
+What is N+1?
+├── 1 query to get parent records
+├── N queries to get related records
+└── Very slow!
+
+Solutions:
+├── JOIN → Single query with all data
+├── Eager loading → ORM handles JOIN
+├── DataLoader → Batch and cache (GraphQL)
+└── Subquery → Fetch related in one query
+```
+
+## Query Analysis Mindset
+
+```
+Before optimizing:
+├── EXPLAIN ANALYZE the query
+├── Look for Seq Scan (full table scan)
+├── Check actual vs estimated rows
+└── Identify missing indexes
+```
+
+## Optimization Priorities
+
+1. **Add missing indexes** (most common issue)
+2. **Select only needed columns** (not SELECT *)
+3. **Use proper JOINs** (avoid subqueries when possible)
+4. **Limit early** (pagination at database level)
+5. **Cache** (when appropriate)

package/.agent/skills/database-design/orm-selection.md

@@ -0,0 +1,30 @@
+# ORM Selection (2025)
+
+> Choose ORM based on deployment and DX needs.
+
+## Decision Tree
+
+```
+What's the context?
+│
+├── Edge deployment / Bundle size matters
+│   └── Drizzle (smallest, SQL-like)
+│
+├── Best DX / Schema-first
+│   └── Prisma (migrations, studio)
+│
+├── Maximum control
+│   └── Raw SQL with query builder
+│
+└── Python ecosystem
+    └── SQLAlchemy 2.0 (async support)
+```
+
+## Comparison
+
+| ORM | Best For | Trade-offs |
+|-----|----------|------------|
+| **Drizzle** | Edge, TypeScript | Newer, less examples |
+| **Prisma** | DX, schema management | Heavier, not edge-ready |
+| **Kysely** | Type-safe SQL builder | Manual migrations |
+| **Raw SQL** | Complex queries, control | Manual type safety |

package/.agent/skills/database-design/schema-design.md

@@ -0,0 +1,56 @@
+# Schema Design Principles
+
+> Normalization, primary keys, timestamps, relationships.
+
+## Normalization Decision
+
+```
+When to normalize (separate tables):
+├── Data is repeated across rows
+├── Updates would need multiple changes
+├── Relationships are clear
+└── Query patterns benefit
+
+When to denormalize (embed/duplicate):
+├── Read performance critical
+├── Data rarely changes
+├── Always fetched together
+└── Simpler queries needed
+```
+
+## Primary Key Selection
+
+| Type | Use When |
+|------|----------|
+| **UUID** | Distributed systems, security |
+| **ULID** | UUID + sortable by time |
+| **Auto-increment** | Simple apps, single database |
+| **Natural key** | Rarely (business meaning) |
+
+## Timestamp Strategy
+
+```
+For every table:
+├── created_at → When created
+├── updated_at → Last modified
+└── deleted_at → Soft delete (if needed)
+
+Use TIMESTAMPTZ (with timezone) not TIMESTAMP
+```
+
+## Relationship Types
+
+| Type | When | Implementation |
+|------|------|----------------|
+| **One-to-One** | Extension data | Separate table with FK |
+| **One-to-Many** | Parent-children | FK on child table |
+| **Many-to-Many** | Both sides have many | Junction table |
+
+## Foreign Key ON DELETE
+
+```
+├── CASCADE → Delete children with parent
+├── SET NULL → Children become orphans
+├── RESTRICT → Prevent delete if children exist
+└── SET DEFAULT → Children get default value
+```

package/.agent/skills/database-design/scripts/schema_validator.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""
+Schema Validator - Database schema validation
+Validates Prisma schemas and checks for common issues.
+
+Usage:
+    python schema_validator.py <project_path>
+
+Checks:
+    - Prisma schema syntax
+    - Missing relations
+    - Index recommendations
+    - Naming conventions
+"""
+
+import sys
+import json
+import re
+from pathlib import Path
+from datetime import datetime
+
+# Fix Windows console encoding
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except:
+    pass
+
+
+def find_schema_files(project_path: Path) -> list:
+    """Find database schema files."""
+    schemas = []
+    
+    # Prisma schema
+    prisma_files = list(project_path.glob('**/prisma/schema.prisma'))
+    schemas.extend([('prisma', f) for f in prisma_files])
+    
+    # Drizzle schema files
+    drizzle_files = list(project_path.glob('**/drizzle/*.ts'))
+    drizzle_files.extend(project_path.glob('**/schema/*.ts'))
+    for f in drizzle_files:
+        if 'schema' in f.name.lower() or 'table' in f.name.lower():
+            schemas.append(('drizzle', f))
+    
+    return schemas[:10]  # Limit
+
+
+def validate_prisma_schema(file_path: Path) -> list:
+    """Validate Prisma schema file."""
+    issues = []
+    
+    try:
+        content = file_path.read_text(encoding='utf-8', errors='ignore')
+        
+        # Find all models
+        models = re.findall(r'model\s+(\w+)\s*{([^}]+)}', content, re.DOTALL)
+        
+        for model_name, model_body in models:
+            # Check naming convention (PascalCase)
+            if not model_name[0].isupper():
+                issues.append(f"Model '{model_name}' should be PascalCase")
+            
+            # Check for id field
+            if '@id' not in model_body and 'id' not in model_body.lower():
+                issues.append(f"Model '{model_name}' might be missing @id field")
+            
+            # Check for createdAt/updatedAt
+            if 'createdAt' not in model_body and 'created_at' not in model_body:
+                issues.append(f"Model '{model_name}' missing createdAt field (recommended)")
+            
+            # Check for @relation without fields
+            relations = re.findall(r'@relation\([^)]*\)', model_body)
+            for rel in relations:
+                if 'fields:' not in rel and 'references:' not in rel:
+                    pass  # Implicit relation, ok
+            
+            # Check for @@index suggestions
+            foreign_keys = re.findall(r'(\w+Id)\s+\w+', model_body)
+            for fk in foreign_keys:
+                if f'@@index([{fk}])' not in content and f'@@index(["{fk}"])' not in content:
+                    issues.append(f"Consider adding @@index([{fk}]) for better query performance in {model_name}")
+        
+        # Check for enum definitions
+        enums = re.findall(r'enum\s+(\w+)\s*{', content)
+        for enum_name in enums:
+            if not enum_name[0].isupper():
+                issues.append(f"Enum '{enum_name}' should be PascalCase")
+        
+    except Exception as e:
+        issues.append(f"Error reading schema: {str(e)[:50]}")
+    
+    return issues
+
+
+def main():
+    project_path = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
+    
+    print(f"\n{'='*60}")
+    print(f"[SCHEMA VALIDATOR] Database Schema Validation")
+    print(f"{'='*60}")
+    print(f"Project: {project_path}")
+    print(f"Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    print("-"*60)
+    
+    # Find schema files
+    schemas = find_schema_files(project_path)
+    print(f"Found {len(schemas)} schema files")
+    
+    if not schemas:
+        output = {
+            "script": "schema_validator",
+            "project": str(project_path),
+            "schemas_checked": 0,
+            "issues_found": 0,
+            "passed": True,
+            "message": "No schema files found"
+        }
+        print(json.dumps(output, indent=2))
+        sys.exit(0)
+    
+    # Validate each schema
+    all_issues = []
+    
+    for schema_type, file_path in schemas:
+        print(f"\nValidating: {file_path.name} ({schema_type})")
+        
+        if schema_type == 'prisma':
+            issues = validate_prisma_schema(file_path)
+        else:
+            issues = []  # Drizzle validation could be added
+        
+        if issues:
+            all_issues.append({
+                "file": str(file_path.name),
+                "type": schema_type,
+                "issues": issues
+            })
+    
+    # Summary
+    print("\n" + "="*60)
+    print("SCHEMA ISSUES")
+    print("="*60)
+    
+    if all_issues:
+        for item in all_issues:
+            print(f"\n{item['file']} ({item['type']}):")
+            for issue in item["issues"][:5]:  # Limit per file
+                print(f"  - {issue}")
+            if len(item["issues"]) > 5:
+                print(f"  ... and {len(item['issues']) - 5} more issues")
+    else:
+        print("No schema issues found!")
+    
+    total_issues = sum(len(item["issues"]) for item in all_issues)
+    # Schema issues are warnings, not failures
+    passed = True
+    
+    output = {
+        "script": "schema_validator",
+        "project": str(project_path),
+        "schemas_checked": len(schemas),
+        "issues_found": total_issues,
+        "passed": passed,
+        "issues": all_issues
+    }
+    
+    print("\n" + json.dumps(output, indent=2))
+    
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/.agent/skills/database-design/supabase-security-egress.md

@@ -0,0 +1,42 @@
+# Supabase Security and Egress Baseline
+
+Use this reference when the system depends on Supabase and the goal includes security, traffic reduction, or storage economy.
+
+## Security defaults
+
+- Enable RLS on every table in exposed schemas such as `public`
+- Grant only the minimum role privileges required for `anon`, `authenticated`, and `service_role`
+- Never expose `service_role` in frontend code or `NEXT_PUBLIC_*`
+- Keep sensitive logic in server code, RPCs, or Edge Functions with strict auth checks
+- If using `SECURITY DEFINER`, keep it in a non-exposed schema, lock `search_path`, and restrict `EXECUTE`
+
+## Query and egress reduction
+
+- Avoid `SELECT *`; return only required columns
+- Always paginate list endpoints and apply `LIMIT`
+- Index columns used by filters, joins, sorting, and RLS predicates
+- Review repeated expensive joins; consider RPCs or materialized views when the access pattern is stable
+- For RLS policies using `auth.uid()` or similar helpers, prefer the cached `select auth.uid()` pattern when row-independent
+
+## Storage economy
+
+- Do not store large PDFs, videos, backups, archives, or heavy images in Supabase when project rules require external storage
+- Store only the link, minimal metadata, checksum, and ownership reference in Supabase
+- Use public buckets only for non-sensitive assets that benefit from CDN caching
+- Prefer Smart CDN and image transformations for cacheable images
+
+## Traffic control
+
+- Check Billing Dashboard, project reports, Top Paths, and query performance before changing compute size
+- Watch database egress, storage egress, auth egress, realtime usage, and edge function invocations separately
+- Use rate limiting for auth flows and expensive Edge Functions
+- For data-heavy Edge Functions, prefer running in the same region as the database
+- Avoid Realtime subscriptions when polling or one-time reads are enough
+
+## Review questions
+
+1. Is the data sensitive enough to require private access only?
+2. Can this response return fewer columns or fewer rows?
+3. Can this file live outside Supabase with only metadata stored here?
+4. Is egress coming from database rows, storage assets, auth churn, realtime, or functions?
+5. Are we paying compute to compensate for inefficient queries or missing indexes?