@ngxtm/devkit 3.3.0 → 3.4.1

package/rules/golang/gorm-orm/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: GORM ORM
+description: Full-featured Go ORM with associations, hooks, and migrations.
+metadata:
+  labels: [golang, gorm, orm, database]
+  triggers:
+    files: ['**/models/*.go', '**/main.go']
+    keywords: [gorm, gorm.Model, gorm.Open, db.Create]
+---
+
+# GORM Standards
+
+## Database Connection
+
+```go
+import (
+    "gorm.io/gorm"
+    "gorm.io/driver/postgres"
+)
+
+func InitDB() (*gorm.DB, error) {
+    dsn := "host=localhost user=postgres password=pass dbname=app port=5432 sslmode=disable"
+    db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{
+        Logger: logger.Default.LogMode(logger.Info),
+    })
+    if err != nil {
+        return nil, err
+    }
+
+    // Connection pool settings
+    sqlDB, _ := db.DB()
+    sqlDB.SetMaxIdleConns(10)
+    sqlDB.SetMaxOpenConns(100)
+    sqlDB.SetConnMaxLifetime(time.Hour)
+
+    return db, nil
+}
+```
+
+## Models
+
+```go
+type User struct {
+    gorm.Model           // ID, CreatedAt, UpdatedAt, DeletedAt
+    Name     string      `gorm:"size:100;not null"`
+    Email    string      `gorm:"uniqueIndex;not null"`
+    Age      int         `gorm:"default:0"`
+    Profile  Profile     `gorm:"constraint:OnDelete:CASCADE;"`
+    Posts    []Post      `gorm:"foreignKey:AuthorID"`
+}
+
+type Profile struct {
+    ID     uint
+    UserID uint   `gorm:"uniqueIndex"`
+    Bio    string `gorm:"type:text"`
+}
+
+type Post struct {
+    ID       uint
+    Title    string
+    AuthorID uint
+    Author   User `gorm:"foreignKey:AuthorID"`
+}
+```
+
+## CRUD Operations
+
+```go
+// Create
+user := User{Name: "John", Email: "john@example.com"}
+result := db.Create(&user)  // user.ID is set after insert
+
+// Create in batches
+users := []User{{Name: "A"}, {Name: "B"}, {Name: "C"}}
+db.CreateInBatches(users, 100)
+
+// Read
+var user User
+db.First(&user, 1)                      // By primary key
+db.First(&user, "email = ?", "john@example.com")
+db.Where("age > ?", 18).Find(&users)    // Multiple results
+
+// Update
+db.Model(&user).Update("Name", "Jane")
+db.Model(&user).Updates(User{Name: "Jane", Age: 25})
+db.Model(&user).Updates(map[string]interface{}{"name": "Jane", "age": 25})
+
+// Delete (soft delete with gorm.Model)
+db.Delete(&user, 1)
+
+// Permanent delete
+db.Unscoped().Delete(&user, 1)
+```
+
+## Queries
+
+```go
+// Conditions
+db.Where("name = ?", "John").Find(&users)
+db.Where("name IN ?", []string{"John", "Jane"}).Find(&users)
+db.Where("age BETWEEN ? AND ?", 18, 65).Find(&users)
+
+// Order, Limit, Offset
+db.Order("created_at desc").Limit(10).Offset(20).Find(&users)
+
+// Select specific columns
+db.Select("name", "email").Find(&users)
+
+// Group and Having
+db.Model(&User{}).Select("name, sum(age)").Group("name").Having("sum(age) > ?", 100).Find(&results)
+
+// Joins
+db.Joins("Profile").Find(&users)  // Preload with join
+
+// Raw SQL
+db.Raw("SELECT * FROM users WHERE age > ?", 18).Scan(&users)
+```
+
+## Associations
+
+```go
+// Preload (eager loading)
+db.Preload("Posts").Find(&users)
+db.Preload("Posts.Comments").Find(&users)  // Nested
+db.Preload("Posts", "published = ?", true).Find(&users)  // Conditional
+
+// Association operations
+db.Model(&user).Association("Posts").Append(&post)
+db.Model(&user).Association("Posts").Delete(&post)
+db.Model(&user).Association("Posts").Clear()
+db.Model(&user).Association("Posts").Count()
+```
+
+## Transactions
+
+```go
+// Automatic transaction
+err := db.Transaction(func(tx *gorm.DB) error {
+    if err := tx.Create(&user).Error; err != nil {
+        return err  // Rollback
+    }
+    if err := tx.Create(&profile).Error; err != nil {
+        return err  // Rollback
+    }
+    return nil  // Commit
+})
+
+// Manual transaction
+tx := db.Begin()
+if err := tx.Create(&user).Error; err != nil {
+    tx.Rollback()
+    return err
+}
+if err := tx.Create(&profile).Error; err != nil {
+    tx.Rollback()
+    return err
+}
+tx.Commit()
+```
+
+## Hooks
+
+```go
+// BeforeCreate
+func (u *User) BeforeCreate(tx *gorm.DB) error {
+    u.UUID = uuid.New()
+    return nil
+}
+
+// AfterCreate
+func (u *User) AfterCreate(tx *gorm.DB) error {
+    // Send welcome email
+    return nil
+}
+
+// BeforeUpdate, AfterUpdate, BeforeDelete, AfterDelete, AfterFind
+```
+
+## Migrations
+
+```go
+// Auto migrate (development only)
+db.AutoMigrate(&User{}, &Post{}, &Profile{})
+
+// For production, use golang-migrate/migrate
+// migrations/000001_create_users.up.sql
+// migrations/000001_create_users.down.sql
+```
+
+## Best Practices
+
+1. **Avoid N+1**: Use `Preload` or `Joins` for associations
+2. **Transactions**: Wrap related operations in transactions
+3. **Indexes**: Add `gorm:"index"` for frequently queried columns
+4. **Soft delete**: Use `gorm.Model` for soft delete, `Unscoped()` for hard delete
+5. **Migrations**: Use migration tools for production, not AutoMigrate

package/rules/golang/gorm-orm/references/REFERENCE.md

@@ -0,0 +1,14 @@
+# GORM ORM References
+
+## References
+
+- [**Model Definitions**](model-definitions.md) - Structs, tags, relationships
+- [**Query Patterns**](query-patterns.md) - CRUD, conditions, preloading
+
+## Quick Checks
+
+- [ ] Use appropriate field tags for constraints
+- [ ] Define relationships with proper foreign keys
+- [ ] Use Preload for eager loading associations
+- [ ] Transaction for multi-operation consistency
+- [ ] Soft delete with gorm.DeletedAt

package/rules/golang/gorm-orm/references/model-definitions.md

@@ -0,0 +1,167 @@
+# GORM Model Definitions
+
+## Basic Model
+
+```go
+import (
+    "time"
+    "gorm.io/gorm"
+)
+
+type User struct {
+    ID        uint           `gorm:"primaryKey"`
+    CreatedAt time.Time
+    UpdatedAt time.Time
+    DeletedAt gorm.DeletedAt `gorm:"index"`
+    
+    Name      string         `gorm:"size:255;not null"`
+    Email     string         `gorm:"uniqueIndex;size:255"`
+    Age       int            `gorm:"default:0"`
+    Active    bool           `gorm:"default:true"`
+}
+
+// Or embed gorm.Model for ID, CreatedAt, UpdatedAt, DeletedAt
+type Post struct {
+    gorm.Model
+    Title   string `gorm:"size:255;not null"`
+    Content string `gorm:"type:text"`
+    UserID  uint
+}
+```
+
+## Field Tags
+
+```go
+type Product struct {
+    // Primary key
+    ID uint `gorm:"primaryKey;autoIncrement"`
+    
+    // Column name
+    ProductName string `gorm:"column:name"`
+    
+    // Size and type
+    Description string `gorm:"type:text"`
+    Code        string `gorm:"size:50"`
+    
+    // Constraints
+    SKU    string  `gorm:"uniqueIndex;not null"`
+    Price  float64 `gorm:"not null;check:price >= 0"`
+    Stock  int     `gorm:"default:0"`
+    
+    // Index
+    Category string `gorm:"index"`
+    
+    // Composite index
+    TenantID uint   `gorm:"uniqueIndex:idx_tenant_sku"`
+    ItemSKU  string `gorm:"uniqueIndex:idx_tenant_sku"`
+    
+    // Ignore field
+    TempData string `gorm:"-"`
+    
+    // Read only
+    ViewCount int `gorm:"->"`
+}
+```
+
+## Relationships
+
+```go
+// One-to-Many
+type User struct {
+    gorm.Model
+    Name  string
+    Posts []Post `gorm:"foreignKey:AuthorID"`
+}
+
+type Post struct {
+    gorm.Model
+    Title    string
+    AuthorID uint
+    Author   User `gorm:"foreignKey:AuthorID"`
+}
+
+// Many-to-Many
+type User struct {
+    gorm.Model
+    Name  string
+    Roles []Role `gorm:"many2many:user_roles;"`
+}
+
+type Role struct {
+    gorm.Model
+    Name  string
+    Users []User `gorm:"many2many:user_roles;"`
+}
+
+// Has One
+type User struct {
+    gorm.Model
+    Name    string
+    Profile Profile
+}
+
+type Profile struct {
+    gorm.Model
+    UserID uint `gorm:"uniqueIndex"`
+    Bio    string
+}
+
+// Belongs To
+type Post struct {
+    gorm.Model
+    Title      string
+    CategoryID uint
+    Category   Category
+}
+
+type Category struct {
+    gorm.Model
+    Name string
+}
+```
+
+## Polymorphic Relations
+
+```go
+type Comment struct {
+    gorm.Model
+    Content       string
+    CommentableID uint
+    CommentableType string
+}
+
+type Post struct {
+    gorm.Model
+    Title    string
+    Comments []Comment `gorm:"polymorphic:Commentable;"`
+}
+
+type Video struct {
+    gorm.Model
+    URL      string
+    Comments []Comment `gorm:"polymorphic:Commentable;"`
+}
+```
+
+## Custom Types
+
+```go
+import "database/sql/driver"
+
+type JSON map[string]interface{}
+
+func (j JSON) Value() (driver.Value, error) {
+    return json.Marshal(j)
+}
+
+func (j *JSON) Scan(value interface{}) error {
+    bytes, _ := value.([]byte)
+    return json.Unmarshal(bytes, &j)
+}
+
+type Product struct {
+    gorm.Model
+    Name     string
+    Metadata JSON `gorm:"type:jsonb"`
+}
+```

package/rules/golang/gorm-orm/references/query-patterns.md

@@ -0,0 +1,161 @@
+# GORM Query Patterns
+
+## Basic CRUD
+
+```go
+// Create
+user := User{Name: "John", Email: "john@example.com"}
+result := db.Create(&user) // user.ID populated after insert
+if result.Error != nil {
+    return result.Error
+}
+
+// Batch create
+users := []User{{Name: "A"}, {Name: "B"}, {Name: "C"}}
+db.Create(&users)
+
+// Read
+var user User
+db.First(&user, 1) // by primary key
+db.First(&user, "id = ?", 1)
+db.Find(&users) // all records
+
+// Update
+db.Model(&user).Update("Name", "Jane")
+db.Model(&user).Updates(User{Name: "Jane", Age: 30})
+db.Model(&user).Updates(map[string]interface{}{"name": "Jane", "age": 30})
+
+// Delete
+db.Delete(&user, 1)
+db.Where("name = ?", "John").Delete(&User{})
+```
+
+## Conditions
+
+```go
+// Where
+db.Where("name = ?", "John").First(&user)
+db.Where("name = ? AND age >= ?", "John", 18).Find(&users)
+db.Where("name IN ?", []string{"John", "Jane"}).Find(&users)
+db.Where("name LIKE ?", "%john%").Find(&users)
+
+// Struct condition
+db.Where(&User{Name: "John", Age: 30}).Find(&users)
+
+// Map condition
+db.Where(map[string]interface{}{"name": "John", "age": 30}).Find(&users)
+
+// Or
+db.Where("name = ?", "John").Or("name = ?", "Jane").Find(&users)
+
+// Not
+db.Not("name = ?", "John").Find(&users)
+
+// Select specific fields
+db.Select("name", "age").Find(&users)
+db.Select("COALESCE(age, 0) as age").Find(&users)
+
+// Order
+db.Order("age desc, name").Find(&users)
+
+// Limit & Offset
+db.Limit(10).Offset(20).Find(&users)
+```
+
+## Preloading (Eager Loading)
+
+```go
+// Preload associations
+db.Preload("Posts").Find(&users)
+db.Preload("Posts.Comments").Find(&users)
+
+// Preload with conditions
+db.Preload("Posts", "published = ?", true).Find(&users)
+
+// Preload with custom query
+db.Preload("Posts", func(db *gorm.DB) *gorm.DB {
+    return db.Order("posts.created_at DESC").Limit(5)
+}).Find(&users)
+
+// Preload all
+db.Preload(clause.Associations).Find(&users)
+
+// Joins
+db.Joins("Profile").Find(&users)
+db.Joins("JOIN posts ON posts.user_id = users.id").
+    Where("posts.title = ?", "Hello").
+    Find(&users)
+```
+
+## Transactions
+
+```go
+// Automatic transaction
+err := db.Transaction(func(tx *gorm.DB) error {
+    if err := tx.Create(&user).Error; err != nil {
+        return err // rollback
+    }
+
+    if err := tx.Create(&post).Error; err != nil {
+        return err // rollback
+    }
+
+    return nil // commit
+})
+
+// Manual transaction
+tx := db.Begin()
+if err := tx.Create(&user).Error; err != nil {
+    tx.Rollback()
+    return err
+}
+if err := tx.Create(&post).Error; err != nil {
+    tx.Rollback()
+    return err
+}
+tx.Commit()
+
+// Nested transactions (savepoints)
+db.Transaction(func(tx *gorm.DB) error {
+    tx.Create(&user)
+    
+    tx.Transaction(func(tx2 *gorm.DB) error {
+        tx2.Create(&post)
+        return errors.New("rollback post only")
+    })
+    
+    return nil // user is committed
+})
+```
+
+## Scopes
+
+```go
+// Define reusable scopes
+func Active(db *gorm.DB) *gorm.DB {
+    return db.Where("active = ?", true)
+}
+
+func Paginate(page, size int) func(db *gorm.DB) *gorm.DB {
+    return func(db *gorm.DB) *gorm.DB {
+        offset := (page - 1) * size
+        return db.Offset(offset).Limit(size)
+    }
+}
+
+// Usage
+db.Scopes(Active, Paginate(1, 10)).Find(&users)
+```
+
+## Raw SQL
+
+```go
+// Raw query
+db.Raw("SELECT * FROM users WHERE name = ?", "John").Scan(&users)
+
+// Exec
+db.Exec("UPDATE users SET age = ? WHERE name = ?", 30, "John")
+
+// Named arguments
+db.Where("name = @name OR age = @age", sql.Named("name", "John"), sql.Named("age", 30)).Find(&users)
+```