@nextsparkjs/ai-workflow 0.1.0-beta.100

package/claude/skills/database-migrations/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: database-migrations
+description: |
+  PostgreSQL migration patterns with RLS, Better Auth integration, and TIMESTAMPTZ.
+  Covers main tables, meta tables, child entities, and sample data.
+  Use this skill when creating migrations, validating SQL, or generating sample data.
+allowed-tools: Read, Glob, Grep, Bash(python:*)
+version: 1.0.0
+---
+
+# Database Migrations Skill
+
+Patterns and tools for PostgreSQL database migrations with RLS, Better Auth, and strict conventions.
+
+## Architecture Overview
+
+```
+core/migrations/
+├── 001_better_auth_and_functions.sql  # Base auth (DO NOT MODIFY)
+├── 002_auth_tables.sql                # Auth tables (DO NOT MODIFY)
+├── XXX_[entity]_table.sql             # Main entity table
+├── XXX_[entity]_metas.sql             # Meta table (optional)
+├── XXX_[entity]_sample_data.sql       # Sample data (optional)
+└── XXX_[parent]_[child]_table.sql     # Child entities
+```
+
+> **📍 Context-Aware Paths:** Paths shown assume monorepo development. In consumer projects,
+> create migrations in `contents/themes/{theme}/migrations/` instead (use sequence 1001+). Core is read-only.
+> See `core-theme-responsibilities` skill for complete rules.
+
+## When to Use This Skill
+
+- Creating new entity migrations
+- Adding meta tables for entities
+- Creating child entity relationships
+- Validating migration conventions
+- Generating sample data
+
+## Core Principles
+
+### 1. Better Auth Integration
+
+**Better Auth uses TEXT for IDs, not UUID type:**
+
+```sql
+-- ✅ CORRECT
+id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+"userId" TEXT NOT NULL REFERENCES public."users"(id) ON DELETE CASCADE,
+
+-- ❌ WRONG
+id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+```
+
+**Use existing functions (NEVER redefine):**
+- `get_auth_user_id()` - Get current authenticated user ID
+- `set_updated_at()` - Auto-update timestamp trigger
+
+### 2. Field Ordering (MANDATORY)
+
+Fields MUST follow this exact order:
+
+```sql
+CREATE TABLE IF NOT EXISTS public."EntityName" (
+  -- 1. Primary Key (always first)
+  id            TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+
+  -- 2. Relational Fields (foreign keys)
+  "userId"      TEXT NOT NULL REFERENCES public."users"(id) ON DELETE CASCADE,
+  "teamId"      TEXT REFERENCES public."teams"(id) ON DELETE CASCADE,
+
+  -- 3. Entity-specific Fields (business logic)
+  title         TEXT NOT NULL,
+  description   TEXT,
+  content       JSONB,
+  priority      INTEGER DEFAULT 0,
+
+  -- 4. System Fields (always last)
+  status        TEXT DEFAULT 'draft',
+  "createdAt"   TIMESTAMPTZ NOT NULL DEFAULT now(),
+  "updatedAt"   TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+### 3. TIMESTAMPTZ Requirement (CRITICAL)
+
+**ALL timestamps MUST use `TIMESTAMPTZ`, never plain `TIMESTAMP`:**
+
+```sql
+-- ✅ CORRECT
+"createdAt"  TIMESTAMPTZ NOT NULL DEFAULT now(),
+"updatedAt"  TIMESTAMPTZ NOT NULL DEFAULT now(),
+"expiresAt"  TIMESTAMPTZ,
+
+-- ❌ FORBIDDEN
+"createdAt"  TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+```
+
+### 4. CASCADE Rules
+
+```sql
+-- ✅ Main entity tables - ALWAYS use CASCADE
+DROP TABLE IF EXISTS public."EntityName" CASCADE;
+
+-- ✅ Meta tables - NO DROP (removed by parent CASCADE)
+CREATE TABLE IF NOT EXISTS public."EntityName_metas" (...);
+
+-- ✅ Foreign Keys - Use CASCADE for parent-child
+REFERENCES public."Parent"(id) ON DELETE CASCADE
+```
+
+## RLS Patterns (4 Cases)
+
+### Case 1: Private to Owner
+```sql
+CREATE POLICY "Entity owner can do all"
+ON public."Entity"
+FOR ALL TO authenticated
+USING ("userId" = public.get_auth_user_id())
+WITH CHECK ("userId" = public.get_auth_user_id());
+```
+
+### Case 2: Team-Based Access
+```sql
+CREATE POLICY "Entity team can do all"
+ON public."Entity"
+FOR ALL TO authenticated
+USING (
+  "teamId" IN (
+    SELECT "teamId" FROM public."members"
+    WHERE "userId" = public.get_auth_user_id()
+  )
+)
+WITH CHECK (...);
+```
+
+### Case 3: Shared Among Authenticated
+```sql
+CREATE POLICY "Entity any auth can do all"
+ON public."Entity"
+FOR ALL TO authenticated
+USING (true)
+WITH CHECK (true);
+```
+
+### Case 4: Public Read with Auth Write
+```sql
+-- Anonymous can read published
+CREATE POLICY "Entity public can select"
+ON public."Entity"
+FOR SELECT TO anon
+USING (published = TRUE);
+
+-- Authenticated can manage all
+CREATE POLICY "Entity auth can do all"
+ON public."Entity"
+FOR ALL TO authenticated
+USING (true)
+WITH CHECK (true);
+```
+
+## Meta Tables Pattern
+
+**CRITICAL: Always use `"entityId"` for foreign key (never `"postId"`, `"userId"`, etc.)**
+
+```sql
+CREATE TABLE IF NOT EXISTS public."EntityName_metas" (
+  id             TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+  "entityId"     TEXT NOT NULL REFERENCES public."EntityName"(id) ON DELETE CASCADE,
+  "metaKey"      TEXT NOT NULL,
+  "metaValue"    JSONB NOT NULL DEFAULT '{}'::jsonb,
+  "dataType"     TEXT,
+  "isPublic"     BOOLEAN NOT NULL DEFAULT FALSE,
+  "isSearchable" BOOLEAN NOT NULL DEFAULT FALSE,
+  "createdAt"    TIMESTAMPTZ NOT NULL DEFAULT now(),
+  "updatedAt"    TIMESTAMPTZ NOT NULL DEFAULT now(),
+  CONSTRAINT entity_metas_unique_key UNIQUE ("entityId", "metaKey")
+);
+```
+
+## Child Entities Pattern
+
+**CRITICAL: Always use `"parentId"` for foreign key (never `"clientId"`, `"orderId"`, etc.)**
+
+```sql
+CREATE TABLE IF NOT EXISTS public."parent_children" (
+  id              TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+  "parentId"      TEXT NOT NULL REFERENCES public."parent"(id) ON DELETE CASCADE,
+
+  -- Child-specific fields (NO userId - inherited via parent)
+  name            TEXT NOT NULL,
+  description     TEXT,
+
+  -- System fields
+  "createdAt"     TIMESTAMPTZ NOT NULL DEFAULT now(),
+  "updatedAt"     TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- RLS inherits parent access
+CREATE POLICY "Child inherit parent access"
+ON public."parent_children"
+FOR ALL TO authenticated
+USING (
+  EXISTS (
+    SELECT 1 FROM public."parent" p
+    WHERE p.id = "parentId"
+      AND p."userId" = public.get_auth_user_id()
+  )
+)
+WITH CHECK (...);
+```
+
+## Scripts
+
+### Validate Migration Conventions
+```bash
+# Validate a specific migration file
+python3 .claude/skills/database-migrations/scripts/validate-migration.py \
+  --file core/migrations/017_scheduled_actions_table.sql
+
+# Validate all migrations
+python3 .claude/skills/database-migrations/scripts/validate-migration.py \
+  --path core/migrations/
+
+# Strict mode (exit with error if issues found)
+python3 .claude/skills/database-migrations/scripts/validate-migration.py \
+  --path core/migrations/ \
+  --strict
+```
+
+### Generate Sample Data
+```bash
+# Generate sample data for an entity
+python3 .claude/skills/database-migrations/scripts/generate-sample-data.py \
+  --entity posts \
+  --count 20
+
+# With custom team and user IDs
+python3 .claude/skills/database-migrations/scripts/generate-sample-data.py \
+  --entity tasks \
+  --count 10 \
+  --user-id "user-sample-1" \
+  --team-id "team-tmt-001"
+
+# Preview without writing
+python3 .claude/skills/database-migrations/scripts/generate-sample-data.py \
+  --entity products \
+  --dry-run
+```
+
+## Required Indexes
+
+```sql
+-- ============================================
+-- INDEXES
+-- ============================================
+-- Primary relationships
+CREATE INDEX IF NOT EXISTS idx_entity_user_id          ON public."entity"("userId");
+CREATE INDEX IF NOT EXISTS idx_entity_team_id          ON public."entity"("teamId");
+
+-- Common query patterns
+CREATE INDEX IF NOT EXISTS idx_entity_status           ON public."entity"(status);
+CREATE INDEX IF NOT EXISTS idx_entity_created_at       ON public."entity"("createdAt" DESC);
+
+-- Conditional indexes
+CREATE INDEX IF NOT EXISTS idx_entity_published        ON public."entity"(published) WHERE published = TRUE;
+
+-- JSONB indexes
+CREATE INDEX IF NOT EXISTS idx_entity_payload_gin      ON public."entity" USING GIN (payload);
+```
+
+## Trigger Pattern
+
+**Always use existing Better Auth function:**
+
+```sql
+-- ============================================
+-- TRIGGER updatedAt (uses Better Auth function)
+-- ============================================
+DROP TRIGGER IF EXISTS entity_set_updated_at ON public."entity";
+CREATE TRIGGER entity_set_updated_at
+BEFORE UPDATE ON public."entity"
+FOR EACH ROW EXECUTE FUNCTION public.set_updated_at();
+```
+
+## Naming Conventions
+
+| Convention | Example |
+|------------|---------|
+| Table names | camelCase: `"scheduledActions"` |
+| Column names | camelCase: `"createdAt"`, `"userId"` |
+| Index names | snake_case: `idx_entity_user_id` |
+| Policy names | "Entity action description" |
+| Constraint names | snake_case: `entity_metas_unique_key` |
+
+## Anti-Patterns
+
+```sql
+-- ❌ NEVER: Plain TIMESTAMP
+"createdAt" TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+
+-- ❌ NEVER: UUID type (Better Auth uses TEXT)
+id UUID PRIMARY KEY DEFAULT gen_random_uuid()
+
+-- ❌ NEVER: Redefine auth functions
+CREATE OR REPLACE FUNCTION public.get_auth_user_id()...
+
+-- ❌ NEVER: Wrong meta FK naming
+"postId" TEXT NOT NULL REFERENCES public."posts"(id)
+-- ✅ CORRECT: "entityId"
+
+-- ❌ NEVER: Wrong child FK naming
+"clientId" TEXT NOT NULL REFERENCES public."clients"(id)
+-- ✅ CORRECT: "parentId"
+
+-- ❌ NEVER: Business logic in DB triggers
+CREATE FUNCTION calculate_order_totals()...
+```
+
+## Checklist
+
+Before finalizing a migration:
+
+- [ ] Uses TEXT for all ID fields (not UUID type)
+- [ ] References `public."users"` for user relationships
+- [ ] Uses `get_auth_user_id()` in RLS (not redefined)
+- [ ] Uses `set_updated_at()` in triggers (not redefined)
+- [ ] ALL timestamps use `TIMESTAMPTZ` (not `TIMESTAMP`)
+- [ ] Uses `now()` (not `CURRENT_TIMESTAMP`)
+- [ ] Fields follow strict ordering (id → FK → business → system)
+- [ ] Main tables use `DROP ... CASCADE`
+- [ ] Meta tables use `"entityId"` (not entity-specific name)
+- [ ] Child tables use `"parentId"` (not parent-specific name)
+- [ ] Appropriate RLS policies for access pattern
+- [ ] Required indexes created
+- [ ] Sample data uses `ON CONFLICT` clause

package/claude/skills/database-migrations/scripts/generate-sample-data.py

@@ -0,0 +1,284 @@
+#!/usr/bin/env python3
+"""
+Generate Sample Data Script
+
+Generates SQL INSERT statements for sample/test data.
+
+Usage:
+    python generate-sample-data.py --entity ENTITY [--count COUNT]
+
+Options:
+    --entity ENTITY   Entity name (e.g., posts, tasks, products)
+    --count COUNT     Number of records to generate (default: 20)
+    --user-id ID      User ID for ownership (default: user-sample-1)
+    --team-id ID      Team ID for team context (default: team-tmt-001)
+    --dry-run         Preview without writing to file
+    --output FILE     Output file path (default: core/migrations/XXX_entity_sample_data.sql)
+"""
+
+import os
+import sys
+import re
+import random
+import argparse
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import List, Dict
+
+
+def to_pascal_case(name: str) -> str:
+    """Convert kebab-case/snake_case to PascalCase."""
+    return ''.join(x.title() for x in re.split(r'[-_]', name))
+
+
+def to_camel_case(name: str) -> str:
+    """Convert kebab-case/snake_case to camelCase."""
+    parts = re.split(r'[-_]', name)
+    return parts[0].lower() + ''.join(x.title() for x in parts[1:])
+
+
+def get_next_migration_number(migrations_path: Path) -> str:
+    """Get the next available migration number."""
+    if not migrations_path.exists():
+        return "020"
+
+    existing = list(migrations_path.glob("*.sql"))
+    if not existing:
+        return "020"
+
+    numbers = []
+    for f in existing:
+        match = re.match(r'^(\d+)_', f.name)
+        if match:
+            numbers.append(int(match.group(1)))
+
+    if numbers:
+        return str(max(numbers) + 1).zfill(3)
+    return "020"
+
+
+def generate_sample_titles(entity: str, count: int) -> List[str]:
+    """Generate sample titles based on entity type."""
+    templates = {
+        'posts': [
+            "Introduction to {topic}",
+            "Understanding {topic}",
+            "A Guide to {topic}",
+            "Best Practices for {topic}",
+            "Deep Dive into {topic}",
+            "Mastering {topic}",
+            "The Complete {topic} Guide",
+            "Getting Started with {topic}",
+            "{topic} Explained",
+            "Why {topic} Matters",
+        ],
+        'tasks': [
+            "Review {topic} implementation",
+            "Fix {topic} issue",
+            "Update {topic} documentation",
+            "Test {topic} feature",
+            "Refactor {topic} code",
+            "Deploy {topic} to production",
+            "Configure {topic} settings",
+            "Analyze {topic} metrics",
+            "Optimize {topic} performance",
+            "Design {topic} system",
+        ],
+        'products': [
+            "Premium {topic} Package",
+            "Professional {topic} Suite",
+            "Enterprise {topic} Solution",
+            "Basic {topic} Plan",
+            "Advanced {topic} Tools",
+            "Essential {topic} Kit",
+            "Ultimate {topic} Bundle",
+            "Starter {topic} Pack",
+            "{topic} Pro Edition",
+            "{topic} Deluxe Version",
+        ],
+        'default': [
+            "Sample {topic} Item",
+            "Test {topic} Record",
+            "{topic} Example",
+            "Demo {topic} Entry",
+            "New {topic} Data",
+        ]
+    }
+
+    topics = [
+        "React", "TypeScript", "Next.js", "PostgreSQL", "Authentication",
+        "API Design", "Testing", "CI/CD", "Docker", "Kubernetes",
+        "Performance", "Security", "Caching", "Database", "Frontend",
+        "Backend", "DevOps", "Monitoring", "Logging", "Analytics"
+    ]
+
+    template_list = templates.get(entity, templates['default'])
+    titles = []
+
+    for i in range(count):
+        template = template_list[i % len(template_list)]
+        topic = topics[i % len(topics)]
+        titles.append(template.format(topic=topic))
+
+    return titles
+
+
+def generate_slugs(titles: List[str]) -> List[str]:
+    """Generate URL slugs from titles."""
+    slugs = []
+    for title in titles:
+        slug = title.lower()
+        slug = re.sub(r'[^a-z0-9\s-]', '', slug)
+        slug = re.sub(r'\s+', '-', slug)
+        slug = re.sub(r'-+', '-', slug)
+        slugs.append(slug.strip('-'))
+    return slugs
+
+
+def generate_sample_data(
+    entity: str,
+    count: int,
+    user_id: str,
+    team_id: str
+) -> str:
+    """Generate SQL INSERT statements for sample data."""
+
+    table_name = to_camel_case(entity)
+    titles = generate_sample_titles(entity, count)
+    slugs = generate_slugs(titles)
+
+    # Status options
+    statuses = ['draft', 'active', 'published', 'archived']
+
+    # Build SQL
+    lines = [
+        f"-- Migration: XXX_{entity}_sample_data.sql",
+        f"-- Description: Sample data for {entity}",
+        f"-- Date: {datetime.now().strftime('%Y-%m-%d')}",
+        "",
+        "-- ============================================",
+        f"-- SAMPLE {entity.upper()}",
+        "-- ============================================",
+        f'INSERT INTO public."{table_name}" (',
+        "  id,",
+        '  "userId",',
+    ]
+
+    # Add teamId if provided
+    if team_id:
+        lines.append('  "teamId",')
+
+    lines.extend([
+        "  title,",
+        "  slug,",
+        "  description,",
+        "  status,",
+        '  "createdAt",',
+        '  "updatedAt"',
+        ") VALUES",
+    ])
+
+    # Generate records
+    values = []
+    base_date = datetime.now() - timedelta(days=30)
+
+    for i in range(count):
+        record_id = f'{entity[:4]}-sample-{i + 1}'
+        created_at = base_date + timedelta(days=i, hours=random.randint(0, 23))
+        updated_at = created_at + timedelta(days=random.randint(0, 5))
+        status = statuses[i % len(statuses)]
+        description = f"Sample description for {entity} #{i + 1}. This is test data for development."
+
+        value_parts = [
+            f"    '{record_id}'",
+            f"    '{user_id}'",
+        ]
+
+        if team_id:
+            value_parts.append(f"    '{team_id}'")
+
+        value_parts.extend([
+            f"    '{titles[i]}'",
+            f"    '{slugs[i]}'",
+            f"    '{description}'",
+            f"    '{status}'",
+            f"    '{created_at.strftime('%Y-%m-%d %H:%M:%S')}'::timestamptz",
+            f"    '{updated_at.strftime('%Y-%m-%d %H:%M:%S')}'::timestamptz",
+        ])
+
+        values.append("  (\n" + ",\n".join(value_parts) + "\n  )")
+
+    lines.append(",\n".join(values))
+    lines.append("ON CONFLICT (id) DO NOTHING;")
+
+    return "\n".join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Generate sample data')
+    parser.add_argument('--entity', required=True, help='Entity name')
+    parser.add_argument('--count', type=int, default=20, help='Number of records')
+    parser.add_argument('--user-id', default='user-sample-1', help='User ID')
+    parser.add_argument('--team-id', default='team-tmt-001', help='Team ID')
+    parser.add_argument('--dry-run', action='store_true', help='Preview without writing')
+    parser.add_argument('--output', help='Output file path')
+
+    args = parser.parse_args()
+
+    entity = args.entity.lower()
+
+    print(f"\n{'=' * 60}")
+    print("GENERATING SAMPLE DATA")
+    print(f"{'=' * 60}")
+    print(f"Entity: {entity}")
+    print(f"Count: {args.count}")
+    print(f"User ID: {args.user_id}")
+    print(f"Team ID: {args.team_id}")
+    print(f"{'=' * 60}\n")
+
+    # Generate SQL
+    sql_content = generate_sample_data(
+        entity,
+        args.count,
+        args.user_id,
+        args.team_id
+    )
+
+    if args.dry_run:
+        print("DRY RUN - Generated SQL:\n")
+        print("-" * 60)
+        print(sql_content)
+        print("-" * 60)
+        print("\nRun without --dry-run to write to file.")
+        return 0
+
+    # Determine output path
+    if args.output:
+        output_path = Path(args.output)
+    else:
+        migrations_path = Path('core/migrations')
+        next_num = get_next_migration_number(migrations_path)
+        output_path = migrations_path / f"{next_num}_{entity}_sample_data.sql"
+
+    # Write file
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(output_path, 'w', encoding='utf-8') as f:
+        f.write(sql_content)
+        f.write('\n')
+
+    print(f"Sample data written to: {output_path}")
+    print(f"Records generated: {args.count}")
+    print(f"\n{'=' * 60}")
+    print("NEXT STEPS:")
+    print("=" * 60)
+    print(f"1. Review generated file: {output_path}")
+    print("2. Adjust fields as needed for your entity schema")
+    print("3. Run migration: pnpm db:migrate")
+    print("=" * 60 + "\n")
+
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())