@nextsparkjs/core 0.1.0-beta.8 → 0.1.0-beta.82

package/dist/presets/ai-workflow/claude/commands/db:fix.md

@@ -1,385 +0,0 @@
----
-description: Test and fix database migrations iteratively until success
----
-
-# Database Fix - Iterative Migration Repair
-
-You are fixing database migration issues through iterative testing and correction.
-
-**Migration File or Error Description:**
-{{{ input }}}
-
----
-
-## Your Mission
-
-Fix database migration issues through an iterative loop:
-
-1. **Run the migration** to identify errors
-2. **Analyze the error** to understand the root cause
-3. **Fix the migration** SQL or schema
-4. **Retry until success** (max 5 attempts)
-5. **Document the fix** for future reference
-
----
-
-## Migration Fix Protocol
-
-### Step 1: Identify Migration File
-
-```typescript
-// If input is a file path
-const migrationPath = input
-
-// If input is an error description, find related migration
-await Glob('migrations/*.sql')
-
-// Read the migration file
-await Read(migrationPath)
-```
-
-### Step 2: Run Migration and Capture Error
-
-```typescript
-await Bash({
-  command: 'pnpm db:migrate 2>&1',
-  description: 'Run database migration'
-})
-
-// Or run specific migration
-await Bash({
-  command: `psql $DATABASE_URL -f ${migrationPath} 2>&1`,
-  description: 'Run specific migration file'
-})
-```
-
-### Step 3: Analyze Error Type
-
-**Common PostgreSQL Errors:**
-
-| Error Code | Description | Common Fix |
-|------------|-------------|------------|
-| `42P01` | Undefined table | Create table first or fix reference |
-| `42P07` | Duplicate table | Add `IF NOT EXISTS` |
-| `42703` | Undefined column | Check column name spelling |
-| `42701` | Duplicate column | Remove duplicate or use `IF NOT EXISTS` |
-| `23503` | Foreign key violation | Fix reference or add missing data |
-| `23505` | Unique violation | Handle duplicates in sample data |
-| `42883` | Undefined function | Create function or fix name |
-| `42804` | Datatype mismatch | Fix column type casting |
-| `22P02` | Invalid text representation | Fix UUID format or type |
-| `42P16` | Invalid table definition | Fix table structure |
-
-### Step 4: Apply Fix
-
-```typescript
-const MAX_ATTEMPTS = 5
-
-for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
-  console.log(`Attempt ${attempt}/${MAX_ATTEMPTS}`)
-
-  // Run migration
-  const result = await Bash({
-    command: `psql $DATABASE_URL -f ${migrationPath} 2>&1`,
-    description: `Migration attempt ${attempt}`
-  })
-
-  if (result.success) {
-    console.log('Migration successful!')
-    break
-  }
-
-  // Analyze error
-  const error = parsePostgresError(result.stderr)
-
-  // Apply appropriate fix
-  switch (error.code) {
-    case '42P01': // Undefined table
-      await fixUndefinedTable(error, migrationPath)
-      break
-
-    case '42P07': // Duplicate table
-      await fixDuplicateTable(error, migrationPath)
-      break
-
-    case '42703': // Undefined column
-      await fixUndefinedColumn(error, migrationPath)
-      break
-
-    case '23503': // Foreign key violation
-      await fixForeignKeyViolation(error, migrationPath)
-      break
-
-    case '23505': // Unique violation
-      await fixUniqueViolation(error, migrationPath)
-      break
-
-    default:
-      await analyzeAndFixGenericError(error, migrationPath)
-  }
-}
-```
-
----
-
-## Common Fix Patterns
-
-### Fix: Undefined Table (42P01)
-
-```typescript
-// Error: relation "user" does not exist
-// Problem: Referencing table that doesn't exist
-
-await Edit({
-  file_path: migrationPath,
-  old_string: 'REFERENCES user(id)',
-  new_string: 'REFERENCES "user"(id)'  // Quote reserved word
-})
-
-// Or if table truly missing, add dependency comment
-await Edit({
-  file_path: migrationPath,
-  old_string: '-- Migration:',
-  new_string: `-- Migration:
--- DEPENDS ON: 001_create_user.sql`
-})
-```
-
-### Fix: Duplicate Table (42P07)
-
-```typescript
-// Error: relation "entity" already exists
-// Fix: Add IF NOT EXISTS
-
-await Edit({
-  file_path: migrationPath,
-  old_string: 'CREATE TABLE entity (',
-  new_string: 'CREATE TABLE IF NOT EXISTS entity ('
-})
-```
-
-### Fix: Undefined Column (42703)
-
-```typescript
-// Error: column "user_id" of relation "entity" does not exist
-// Fix: Check spelling or add column
-
-await Edit({
-  file_path: migrationPath,
-  old_string: 'userId UUID',
-  new_string: 'user_id UUID'  // Fix snake_case
-})
-```
-
-### Fix: Foreign Key Violation (23503)
-
-```typescript
-// Error: insert or update violates foreign key constraint
-// Fix: Ensure referenced record exists
-
-await Edit({
-  file_path: migrationPath,
-  old_string: "VALUES ('hardcoded-user-id',",
-  new_string: `VALUES (
-    (SELECT id FROM "user" WHERE email = 'superadmin@nextspark.dev' LIMIT 1),`
-})
-```
-
-### Fix: Unique Violation (23505)
-
-```typescript
-// Error: duplicate key value violates unique constraint
-// Fix: Use ON CONFLICT or unique IDs
-
-await Edit({
-  file_path: migrationPath,
-  old_string: 'INSERT INTO entity',
-  new_string: `INSERT INTO entity
-ON CONFLICT (id) DO UPDATE SET updated_at = NOW()`
-})
-```
-
-### Fix: Function Not Found (42883)
-
-```typescript
-// Error: function uuid_generate_v4() does not exist
-// Fix: Enable extension
-
-await Edit({
-  file_path: migrationPath,
-  old_string: '-- Migration:',
-  new_string: `-- Migration:
-
--- Enable required extension
-CREATE EXTENSION IF NOT EXISTS "uuid-ossp";`
-})
-```
-
-### Fix: Type Mismatch (42804)
-
-```typescript
-// Error: column "amount" is of type numeric but expression is of type text
-// Fix: Add explicit cast
-
-await Edit({
-  file_path: migrationPath,
-  old_string: "amount = 'value'",
-  new_string: "amount = 'value'::numeric"
-})
-```
-
----
-
-## Step 5: Verify Success
-
-```typescript
-// Verify tables were created
-await Bash({
-  command: 'pnpm db:verify',
-  description: 'Verify database schema'
-})
-
-// Or check specific table
-await Bash({
-  command: `psql $DATABASE_URL -c "\\d ${tableName}"`,
-  description: 'Describe table structure'
-})
-
-// Check row counts
-await Bash({
-  command: `psql $DATABASE_URL -c "SELECT COUNT(*) FROM ${tableName}"`,
-  description: 'Count table rows'
-})
-```
-
----
-
-## Step 6: Document the Fix
-
-```typescript
-// Add comment to migration file explaining fix
-await Edit({
-  file_path: migrationPath,
-  old_string: '-- Migration:',
-  new_string: `-- Migration:
--- FIX APPLIED (${date}):
--- - Issue: ${errorDescription}
--- - Solution: ${fixApplied}
--- - Attempts: ${attemptCount}`
-})
-```
-
----
-
-## Output Format
-
-```markdown
-## Migration Fix Complete
-
-**File:** `${migrationPath}`
-**Attempts:** ${attemptCount}/${MAX_ATTEMPTS}
-**Status:** ✅ Success / ❌ Failed
-
-### Error History
-| Attempt | Error | Fix Applied |
-|---------|-------|-------------|
-| 1 | 42P01: relation "user" does not exist | Added quotes around reserved word |
-| 2 | 42883: function uuid_generate_v4() not found | Added CREATE EXTENSION |
-| 3 | ✅ Success | - |
-
-### Changes Made
-\`\`\`diff
-- REFERENCES user(id)
-+ REFERENCES "user"(id)
-
-+ CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
-\`\`\`
-
-### Verification
-- Tables created: ✅
-- Indexes created: ✅
-- Triggers created: ✅
-- Sample data inserted: ✅
-
-### Lessons Learned
-- Always quote reserved words in PostgreSQL
-- Enable uuid-ossp extension before using uuid_generate_v4()
-- Use IF NOT EXISTS for idempotent migrations
-```
-
----
-
-## Rollback on Failure
-
-If max attempts exceeded:
-
-```typescript
-if (attempt > MAX_ATTEMPTS) {
-  // Generate rollback script
-  await Write({
-    file_path: `migrations/rollback_${entityName}.sql`,
-    content: `-- Rollback for failed migration
--- Generated: ${date}
--- Original file: ${migrationPath}
-
-DROP TABLE IF EXISTS ${tableName} CASCADE;
-DROP FUNCTION IF EXISTS update_${tableName}_updated_at();
-
--- Note: This rollback was generated due to migration failure
--- Review the original migration file for issues
-`
-  })
-
-  console.log(`
-Migration failed after ${MAX_ATTEMPTS} attempts.
-Rollback script generated: migrations/rollback_${entityName}.sql
-
-Manual intervention required. Check:
-1. Database connection (DATABASE_URL)
-2. User permissions
-3. Dependent tables exist
-4. Data type compatibility
-`)
-}
-```
-
----
-
-## Best Practices
-
-### DO:
-- Use `IF NOT EXISTS` for all CREATE statements
-- Quote reserved words (`"user"`, `"order"`, etc.)
-- Add explicit type casts where needed
-- Enable extensions at the start of migration
-- Use transactions for multi-statement migrations
-- Test migrations on a copy of production data
-
-### DON'T:
-- Hardcode UUIDs that might conflict
-- Reference tables before they're created
-- Use reserved words without quotes
-- Assume extensions are already enabled
-- Ignore error messages - they're specific for a reason
-
----
-
-## PostgreSQL Reserved Words (Common Pitfalls)
-
-Always quote these as table/column names:
-- `user`, `order`, `group`, `table`, `select`, `insert`
-- `date`, `time`, `timestamp`, `interval`
-- `key`, `value`, `index`, `type`, `status`
-- `check`, `default`, `primary`, `foreign`
-
-```sql
--- ❌ Wrong
-SELECT * FROM user WHERE order = 1
-
--- ✅ Correct
-SELECT * FROM "user" WHERE "order" = 1
-```
-
----
-
-**Now fix the migration issue described above.**

package/dist/presets/ai-workflow/claude/commands/db:sample.md

@@ -1,266 +0,0 @@
----
-description: "[DB Step 2] Generate coherent sample data for database entities"
----
-
-# Database Sample - Generate Test Data
-
-You are generating sample data for database testing.
-
-**Entity or Table:**
-{{{ input }}}
-
----
-
-## Your Mission
-
-Generate coherent, realistic sample data that:
-
-1. **Respects constraints** (foreign keys, unique, check)
-2. **Creates relationships** between related entities
-3. **Includes edge cases** (empty strings, nulls, max values)
-4. **Is reproducible** (uses deterministic values where possible)
-
----
-
-## Sample Data Generation
-
-### Step 1: Analyze Table Schema
-
-```typescript
-// Read the migration file or check existing schema
-await Bash({
-  command: 'pnpm db:verify',
-  description: 'Check current database schema'
-})
-
-// Or read migration file
-await Read(`migrations/*_create_${entityName}.sql`)
-```
-
-### Step 2: Generate SQL Insert Statements
-
-```typescript
-const samplePath = `migrations/sample_data_${entityName}.sql`
-
-await Write({
-  file_path: samplePath,
-  content: `-- Sample Data: ${entityName}
--- Generated: ${new Date().toISOString()}
--- Purpose: Testing and development
-
--- ============================================
--- SAMPLE ${entityName.toUpperCase()} DATA
--- ============================================
-
--- Clear existing sample data (optional, for rerunning)
--- DELETE FROM ${entityName} WHERE id IN (
---     '00000000-0000-0000-0000-000000000001',
---     '00000000-0000-0000-0000-000000000002',
---     '00000000-0000-0000-0000-000000000003'
--- );
-
--- Sample 1: Basic record
-INSERT INTO ${entityName} (
-    id,
-    user_id,
-    name,
-    description,
-    status,
-    created_at
-) VALUES (
-    '00000000-0000-0000-0000-000000000001',
-    (SELECT id FROM "user" WHERE email = 'superadmin@nextspark.dev' LIMIT 1),
-    'Sample ${EntityName} 1',
-    'This is a sample ${entityName} for testing purposes.',
-    'active',
-    NOW() - INTERVAL '7 days'
-);
-
--- Sample 2: Record with different status
-INSERT INTO ${entityName} (
-    id,
-    user_id,
-    name,
-    description,
-    status,
-    created_at
-) VALUES (
-    '00000000-0000-0000-0000-000000000002',
-    (SELECT id FROM "user" WHERE email = 'superadmin@nextspark.dev' LIMIT 1),
-    'Sample ${EntityName} 2',
-    'Another sample with inactive status.',
-    'inactive',
-    NOW() - INTERVAL '3 days'
-);
-
--- Sample 3: Record with minimal data
-INSERT INTO ${entityName} (
-    id,
-    user_id,
-    name,
-    status
-) VALUES (
-    '00000000-0000-0000-0000-000000000003',
-    (SELECT id FROM "user" WHERE email = 'superadmin@nextspark.dev' LIMIT 1),
-    'Minimal ${EntityName}',
-    'active'
-);
-
--- Sample 4: Record with special characters
-INSERT INTO ${entityName} (
-    id,
-    user_id,
-    name,
-    description,
-    status
-) VALUES (
-    '00000000-0000-0000-0000-000000000004',
-    (SELECT id FROM "user" WHERE email = 'superadmin@nextspark.dev' LIMIT 1),
-    'Test with "quotes" & <special> chars',
-    'Description with unicode: \u00e1\u00e9\u00ed\u00f3\u00fa \u00f1 \u20ac',
-    'active'
-);
-
--- Sample 5: Record for edge case testing (long name)
-INSERT INTO ${entityName} (
-    id,
-    user_id,
-    name,
-    status
-) VALUES (
-    '00000000-0000-0000-0000-000000000005',
-    (SELECT id FROM "user" WHERE email = 'superadmin@nextspark.dev' LIMIT 1),
-    '${Array(50).fill('Long').join(' ')}',
-    'active'
-);
-
-${hasMetadata ? `
--- ============================================
--- SAMPLE METADATA
--- ============================================
-
-INSERT INTO ${entityName}_metadata (${entityName}_id, key, value) VALUES
-    ('00000000-0000-0000-0000-000000000001', 'color', 'blue'),
-    ('00000000-0000-0000-0000-000000000001', 'priority', 'high'),
-    ('00000000-0000-0000-0000-000000000002', 'color', 'red'),
-    ('00000000-0000-0000-0000-000000000002', 'tags', '["tag1", "tag2"]');
-` : ''}
-
-${hasChildEntity ? `
--- ============================================
--- SAMPLE CHILD DATA
--- ============================================
-
-INSERT INTO ${entityName}_${childName} (${entityName}_id, name, sort_order) VALUES
-    ('00000000-0000-0000-0000-000000000001', 'Child Item 1', 0),
-    ('00000000-0000-0000-0000-000000000001', 'Child Item 2', 1),
-    ('00000000-0000-0000-0000-000000000001', 'Child Item 3', 2),
-    ('00000000-0000-0000-0000-000000000002', 'Other Child', 0);
-` : ''}
-
--- ============================================
--- VERIFICATION QUERIES
--- ============================================
-
--- Check data was inserted
-SELECT 'Total ${entityName}:' as label, COUNT(*) as count FROM ${entityName};
-${hasMetadata ? `SELECT 'Total metadata:' as label, COUNT(*) as count FROM ${entityName}_metadata;` : ''}
-${hasChildEntity ? `SELECT 'Total children:' as label, COUNT(*) as count FROM ${entityName}_${childName};` : ''}
-`
-})
-```
-
-### Step 3: Run Sample Data Script
-
-```typescript
-// Execute the sample data SQL
-await Bash({
-  command: `psql $DATABASE_URL -f ${samplePath}`,
-  description: 'Insert sample data'
-})
-
-// Or if using npm script
-await Bash({
-  command: 'pnpm db:sample',
-  description: 'Run sample data script'
-})
-```
-
----
-
-## Sample Data Patterns
-
-### Consistent UUIDs for Testing
-```sql
--- Use predictable UUIDs for testing
-'00000000-0000-0000-0000-000000000001'
-'00000000-0000-0000-0000-000000000002'
--- etc.
-```
-
-### User References
-```sql
--- Reference existing test user
-(SELECT id FROM "user" WHERE email = 'superadmin@nextspark.dev' LIMIT 1)
-```
-
-### Date Ranges
-```sql
--- Records from different time periods
-NOW() - INTERVAL '1 year'
-NOW() - INTERVAL '30 days'
-NOW() - INTERVAL '7 days'
-NOW() - INTERVAL '1 day'
-NOW()
-```
-
-### Status Distribution
-```sql
--- Mix of statuses for testing filters
-'active'    -- Most common
-'inactive'  -- Some inactive
-'pending'   -- Some pending
-'archived'  -- A few archived
-```
-
----
-
-## Output Format
-
-```markdown
-## Sample Data Generated: ${entityName}
-
-### File Created
-- **Path:** `migrations/sample_data_${entityName}.sql`
-
-### Records Created
-- `${entityName}`: 5 sample records
-${hasMetadata ? `- \`${entityName}_metadata\`: 4 metadata entries` : ''}
-${hasChildEntity ? `- \`${entityName}_${childName}\`: 4 child records` : ''}
-
-### Test Coverage
-- Basic CRUD operations
-- Status filtering
-- Special characters in text
-- Long values (edge case)
-- Minimal required fields
-- Full optional fields
-
-### Predictable IDs
-```
-00000000-0000-0000-0000-000000000001 - Basic record
-00000000-0000-0000-0000-000000000002 - Inactive status
-00000000-0000-0000-0000-000000000003 - Minimal data
-00000000-0000-0000-0000-000000000004 - Special characters
-00000000-0000-0000-0000-000000000005 - Edge case (long)
-```
-
-### Next Steps
-1. Run: `pnpm db:sample` or execute SQL directly
-2. Verify with: `pnpm db:verify`
-3. Use in Cypress tests with known IDs
-```
-
----
-
-**Now generate sample data for the entity described above.**