@ngxtm/devkit 3.3.0 → 3.4.1

package/rules/golang/validator/references/validation-tags.md

@@ -0,0 +1,211 @@
+# Validator Validation Tags
+
+## Basic Usage
+
+```go
+import (
+    "github.com/go-playground/validator/v10"
+)
+
+type User struct {
+    Name     string `validate:"required,min=2,max=100"`
+    Email    string `validate:"required,email"`
+    Age      int    `validate:"gte=0,lte=130"`
+    Password string `validate:"required,min=8"`
+}
+
+func main() {
+    validate := validator.New()
+
+    user := User{
+        Name:     "J",
+        Email:    "invalid",
+        Age:      -1,
+        Password: "short",
+    }
+
+    err := validate.Struct(user)
+    if err != nil {
+        for _, err := range err.(validator.ValidationErrors) {
+            fmt.Printf("Field: %s, Tag: %s, Value: %v\n",
+                err.Field(), err.Tag(), err.Value())
+        }
+    }
+}
+```
+
+## Common Tags
+
+```go
+type Example struct {
+    // Required fields
+    Required    string `validate:"required"`
+    RequiredIf  string `validate:"required_if=Type email"`
+    RequiredWith string `validate:"required_with=Other"`
+    
+    // String length
+    MinLen      string `validate:"min=3"`
+    MaxLen      string `validate:"max=100"`
+    Len         string `validate:"len=10"`
+    
+    // Numeric ranges
+    Gt          int    `validate:"gt=0"`
+    Gte         int    `validate:"gte=1"`
+    Lt          int    `validate:"lt=100"`
+    Lte         int    `validate:"lte=99"`
+    
+    // Format validators
+    Email       string `validate:"email"`
+    URL         string `validate:"url"`
+    UUID        string `validate:"uuid"`
+    IP          string `validate:"ip"`
+    IPv4        string `validate:"ipv4"`
+    
+    // Comparisons
+    Eq          string `validate:"eq=admin"`
+    Ne          string `validate:"ne=guest"`
+    OneOf       string `validate:"oneof=red green blue"`
+    
+    // Content
+    Alpha       string `validate:"alpha"`
+    Alphanum    string `validate:"alphanum"`
+    Numeric     string `validate:"numeric"`
+    Contains    string `validate:"contains=@"`
+    StartsWith  string `validate:"startswith=prefix_"`
+    EndsWith    string `validate:"endswith=_suffix"`
+}
+```
+
+## Nested Validation
+
+```go
+type Address struct {
+    Street  string `validate:"required"`
+    City    string `validate:"required"`
+    ZipCode string `validate:"required,numeric,len=5"`
+}
+
+type User struct {
+    Name    string  `validate:"required"`
+    Address Address `validate:"required"` // Validates nested struct
+}
+
+// Slice validation with dive
+type Order struct {
+    Items []OrderItem `validate:"required,dive"` // Validates each item
+}
+
+type OrderItem struct {
+    ProductID string `validate:"required,uuid"`
+    Quantity  int    `validate:"required,gt=0"`
+}
+
+// Map validation
+type Config struct {
+    Settings map[string]string `validate:"dive,keys,required,endkeys,required"`
+}
+```
+
+## Custom Validators
+
+```go
+func main() {
+    validate := validator.New()
+
+    // Custom validation function
+    validate.RegisterValidation("strongpassword", func(fl validator.FieldLevel) bool {
+        password := fl.Field().String()
+        hasUpper := regexp.MustCompile(`[A-Z]`).MatchString(password)
+        hasLower := regexp.MustCompile(`[a-z]`).MatchString(password)
+        hasNumber := regexp.MustCompile(`[0-9]`).MatchString(password)
+        return len(password) >= 8 && hasUpper && hasLower && hasNumber
+    })
+
+    type User struct {
+        Password string `validate:"required,strongpassword"`
+    }
+}
+```
+
+## Conditional Validation
+
+```go
+type Payment struct {
+    Type       string `validate:"required,oneof=card bank crypto"`
+    CardNumber string `validate:"required_if=Type card,omitempty,credit_card"`
+    BankAccount string `validate:"required_if=Type bank,omitempty"`
+    WalletAddress string `validate:"required_if=Type crypto,omitempty"`
+}
+
+type User struct {
+    Type     string `validate:"required,oneof=individual company"`
+    // Required only if Type is "company"
+    CompanyName string `validate:"required_if=Type company"`
+    TaxID       string `validate:"required_if=Type company"`
+}
+```
+
+## Error Handling
+
+```go
+func validateAndRespond(w http.ResponseWriter, data interface{}) error {
+    if err := validate.Struct(data); err != nil {
+        var errors []string
+        
+        for _, err := range err.(validator.ValidationErrors) {
+            field := err.Field()
+            tag := err.Tag()
+            param := err.Param()
+            
+            var message string
+            switch tag {
+            case "required":
+                message = fmt.Sprintf("%s is required", field)
+            case "email":
+                message = fmt.Sprintf("%s must be a valid email", field)
+            case "min":
+                message = fmt.Sprintf("%s must be at least %s characters", field, param)
+            case "max":
+                message = fmt.Sprintf("%s must be at most %s characters", field, param)
+            default:
+                message = fmt.Sprintf("%s failed validation: %s", field, tag)
+            }
+            
+            errors = append(errors, message)
+        }
+        
+        return fmt.Errorf("validation failed: %v", errors)
+    }
+    
+    return nil
+}
+```
+
+## Integration with Gin/Echo
+
+```go
+// Gin
+type CreateUserRequest struct {
+    Name  string `json:"name" binding:"required,min=2"`
+    Email string `json:"email" binding:"required,email"`
+}
+
+func createUser(c *gin.Context) {
+    var req CreateUserRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        c.JSON(400, gin.H{"error": err.Error()})
+        return
+    }
+}
+
+// Echo (custom validator)
+type CustomValidator struct {
+    validator *validator.Validate
+}
+
+func (cv *CustomValidator) Validate(i interface{}) error {
+    return cv.validator.Struct(i)
+}
+
+e.Validator = &CustomValidator{validator: validator.New()}
+```

package/rules/golang/viper-config/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: Viper Config
+description: Complete configuration solution for Go applications.
+metadata:
+  labels: [golang, viper, config, configuration]
+  triggers:
+    files: ['**/config.go', 'config.yaml', 'config.json']
+    keywords: [viper, GetString, SetDefault, ReadInConfig]
+---
+
+# Viper Config Standards
+
+## Basic Setup
+
+```go
+import "github.com/spf13/viper"
+
+func initConfig() {
+    viper.SetConfigName("config")      // config file name (no extension)
+    viper.SetConfigType("yaml")        // config file type
+    viper.AddConfigPath(".")           // look in current dir
+    viper.AddConfigPath("$HOME/.app")  // look in home dir
+    viper.AddConfigPath("/etc/app/")   // look in /etc
+
+    if err := viper.ReadInConfig(); err != nil {
+        if _, ok := err.(viper.ConfigFileNotFoundError); ok {
+            // Config file not found, use defaults
+        } else {
+            log.Fatalf("Error reading config: %v", err)
+        }
+    }
+}
+```
+
+## Configuration File
+
+```yaml
+# config.yaml
+server:
+  host: localhost
+  port: 8080
+  timeout: 30s
+
+database:
+  url: postgres://user:pass@localhost/db
+  max_connections: 100
+
+features:
+  cache_enabled: true
+  debug_mode: false
+
+allowed_origins:
+  - http://localhost:3000
+  - https://example.com
+```
+
+## Reading Values
+
+```go
+// Strings
+host := viper.GetString("server.host")
+
+// Integers
+port := viper.GetInt("server.port")
+
+// Booleans
+debug := viper.GetBool("features.debug_mode")
+
+// Duration
+timeout := viper.GetDuration("server.timeout")
+
+// Slices
+origins := viper.GetStringSlice("allowed_origins")
+
+// Maps
+settings := viper.GetStringMapString("settings")
+
+// Check if key exists
+if viper.IsSet("database.url") {
+    // ...
+}
+```
+
+## Defaults
+
+```go
+func setDefaults() {
+    viper.SetDefault("server.host", "localhost")
+    viper.SetDefault("server.port", 8080)
+    viper.SetDefault("database.max_connections", 10)
+    viper.SetDefault("features.cache_enabled", true)
+}
+```
+
+## Environment Variables
+
+```go
+func initConfig() {
+    // Automatically read env vars
+    viper.AutomaticEnv()
+
+    // Replace . with _ in env var names
+    viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
+
+    // Prefix for env vars: APP_SERVER_PORT
+    viper.SetEnvPrefix("APP")
+
+    // Bind specific env var
+    viper.BindEnv("database.url", "DATABASE_URL")
+}
+
+// Environment: APP_SERVER_PORT=9000
+// viper.GetInt("server.port") returns 9000
+```
+
+## Unmarshal to Struct
+
+```go
+type Config struct {
+    Server   ServerConfig   `mapstructure:"server"`
+    Database DatabaseConfig `mapstructure:"database"`
+}
+
+type ServerConfig struct {
+    Host    string        `mapstructure:"host"`
+    Port    int           `mapstructure:"port"`
+    Timeout time.Duration `mapstructure:"timeout"`
+}
+
+type DatabaseConfig struct {
+    URL            string `mapstructure:"url"`
+    MaxConnections int    `mapstructure:"max_connections"`
+}
+
+func LoadConfig() (*Config, error) {
+    var cfg Config
+    if err := viper.Unmarshal(&cfg); err != nil {
+        return nil, err
+    }
+    return &cfg, nil
+}
+
+// Sub-config
+func LoadServerConfig() (*ServerConfig, error) {
+    var cfg ServerConfig
+    if err := viper.UnmarshalKey("server", &cfg); err != nil {
+        return nil, err
+    }
+    return &cfg, nil
+}
+```
+
+## Live Watching
+
+```go
+import "github.com/fsnotify/fsnotify"
+
+func initConfig() {
+    viper.WatchConfig()
+    viper.OnConfigChange(func(e fsnotify.Event) {
+        fmt.Println("Config changed:", e.Name)
+        // Reload application config
+        reloadConfig()
+    })
+}
+```
+
+## Cobra Integration
+
+```go
+import (
+    "github.com/spf13/cobra"
+    "github.com/spf13/viper"
+)
+
+var cfgFile string
+
+var rootCmd = &cobra.Command{
+    Use: "app",
+    PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
+        return initConfig()
+    },
+}
+
+func init() {
+    rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file")
+    rootCmd.PersistentFlags().Int("port", 8080, "server port")
+
+    // Bind flag to viper
+    viper.BindPFlag("server.port", rootCmd.PersistentFlags().Lookup("port"))
+}
+
+func initConfig() error {
+    if cfgFile != "" {
+        viper.SetConfigFile(cfgFile)
+    } else {
+        viper.SetConfigName("config")
+        viper.AddConfigPath(".")
+    }
+
+    viper.AutomaticEnv()
+    return viper.ReadInConfig()
+}
+```
+
+## Multiple Config Files
+
+```go
+// Merge multiple configs
+viper.SetConfigName("config")
+viper.ReadInConfig()
+
+viper.SetConfigName("config.local")
+viper.MergeInConfig()  // Merge with existing
+
+// Or read specific file
+viper.SetConfigFile("/path/to/config.yaml")
+viper.MergeInConfig()
+```
+
+## Writing Config
+
+```go
+// Write current config
+viper.WriteConfig()
+
+// Write to specific file
+viper.WriteConfigAs("./config.new.yaml")
+
+// Safe write (don't overwrite)
+viper.SafeWriteConfig()
+
+// Set values programmatically
+viper.Set("server.port", 9000)
+viper.WriteConfig()
+```
+
+## Best Practices
+
+1. **Defaults**: Always set sensible defaults
+2. **Environment**: Use `AutomaticEnv()` for 12-factor apps
+3. **Struct binding**: Unmarshal to typed config structs
+4. **Validation**: Validate config after loading
+5. **Secrets**: Use env vars for secrets, not config files

package/rules/golang/viper-config/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# Viper Configuration References
+
+## References
+
+- [**Config Loading**](config-loading.md) - Files, env vars, defaults
+
+## Quick Checks
+
+- [ ] Set sensible defaults
+- [ ] Support multiple config formats
+- [ ] Environment variable overrides
+- [ ] AutomaticEnv for env var binding
+- [ ] Watch for config changes

package/rules/golang/viper-config/references/config-loading.md

@@ -0,0 +1,181 @@
+# Viper Config Loading
+
+## Basic Usage
+
+```go
+import "github.com/spf13/viper"
+
+func LoadConfig() error {
+    // Config file name (without extension)
+    viper.SetConfigName("config")
+    
+    // Config file type
+    viper.SetConfigType("yaml")
+    
+    // Search paths
+    viper.AddConfigPath(".")
+    viper.AddConfigPath("./config")
+    viper.AddConfigPath("$HOME/.myapp")
+    
+    // Read config
+    if err := viper.ReadInConfig(); err != nil {
+        if _, ok := err.(viper.ConfigFileNotFoundError); ok {
+            // Config file not found, use defaults
+        } else {
+            return err
+        }
+    }
+    
+    return nil
+}
+
+// Access values
+func main() {
+    LoadConfig()
+    
+    host := viper.GetString("server.host")
+    port := viper.GetInt("server.port")
+    debug := viper.GetBool("debug")
+    timeout := viper.GetDuration("timeout")
+    hosts := viper.GetStringSlice("allowed_hosts")
+}
+```
+
+## Defaults
+
+```go
+func SetDefaults() {
+    viper.SetDefault("server.host", "localhost")
+    viper.SetDefault("server.port", 8080)
+    viper.SetDefault("database.driver", "postgres")
+    viper.SetDefault("log.level", "info")
+    viper.SetDefault("timeout", "30s")
+}
+```
+
+## Environment Variables
+
+```go
+func LoadConfig() {
+    // Prefix for env vars (e.g., MYAPP_SERVER_PORT)
+    viper.SetEnvPrefix("MYAPP")
+    
+    // Replace dots with underscores in env var names
+    viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
+    
+    // Automatically bind all keys to env vars
+    viper.AutomaticEnv()
+    
+    // Or bind specific keys
+    viper.BindEnv("server.port", "PORT") // Binds PORT env var
+}
+
+// Example: MYAPP_SERVER_PORT=9000 overrides server.port
+```
+
+## Unmarshal to Struct
+
+```go
+type Config struct {
+    Server   ServerConfig   `mapstructure:"server"`
+    Database DatabaseConfig `mapstructure:"database"`
+    Log      LogConfig      `mapstructure:"log"`
+}
+
+type ServerConfig struct {
+    Host string `mapstructure:"host"`
+    Port int    `mapstructure:"port"`
+}
+
+type DatabaseConfig struct {
+    Driver   string `mapstructure:"driver"`
+    Host     string `mapstructure:"host"`
+    Port     int    `mapstructure:"port"`
+    Name     string `mapstructure:"name"`
+    User     string `mapstructure:"user"`
+    Password string `mapstructure:"password"`
+}
+
+type LogConfig struct {
+    Level  string `mapstructure:"level"`
+    Format string `mapstructure:"format"`
+}
+
+func LoadConfig() (*Config, error) {
+    viper.SetConfigName("config")
+    viper.AddConfigPath(".")
+    
+    if err := viper.ReadInConfig(); err != nil {
+        return nil, err
+    }
+    
+    var config Config
+    if err := viper.Unmarshal(&config); err != nil {
+        return nil, err
+    }
+    
+    return &config, nil
+}
+```
+
+## Watch for Changes
+
+```go
+func WatchConfig(onChange func()) {
+    viper.WatchConfig()
+    viper.OnConfigChange(func(e fsnotify.Event) {
+        log.Println("Config file changed:", e.Name)
+        onChange()
+    })
+}
+```
+
+## Multiple Config Files
+
+```go
+func LoadConfigs() error {
+    // Main config
+    viper.SetConfigName("config")
+    viper.AddConfigPath(".")
+    if err := viper.ReadInConfig(); err != nil {
+        return err
+    }
+    
+    // Merge additional config
+    viper.SetConfigName("secrets")
+    if err := viper.MergeInConfig(); err != nil {
+        // Secrets file optional
+    }
+    
+    return nil
+}
+```
+
+## Example Config File
+
+```yaml
+# config.yaml
+server:
+  host: localhost
+  port: 8080
+
+database:
+  driver: postgres
+  host: localhost
+  port: 5432
+  name: myapp
+  user: postgres
+  password: ${DB_PASSWORD}  # Use env var
+
+log:
+  level: info
+  format: json
+
+features:
+  enable_cache: true
+  cache_ttl: 5m
+
+allowed_origins:
+  - http://localhost:3000
+  - https://example.com
+```