@ngxtm/devkit 3.3.0 → 3.4.1

package/rules/golang/core/references/concurrency-patterns.md

@@ -0,0 +1,114 @@
+# Concurrency Patterns
+
+## Goroutines and Channels
+
+```go
+// Worker pool
+func workerPool(jobs <-chan Job, results chan<- Result, workers int) {
+    var wg sync.WaitGroup
+    for i := 0; i < workers; i++ {
+        wg.Add(1)
+        go func() {
+            defer wg.Done()
+            for job := range jobs {
+                results <- process(job)
+            }
+        }()
+    }
+    wg.Wait()
+    close(results)
+}
+
+// Fan-out, fan-in
+func fanOut(input <-chan int, workers int) []<-chan int {
+    channels := make([]<-chan int, workers)
+    for i := 0; i < workers; i++ {
+        channels[i] = worker(input)
+    }
+    return channels
+}
+
+func fanIn(channels ...<-chan int) <-chan int {
+    out := make(chan int)
+    var wg sync.WaitGroup
+    for _, ch := range channels {
+        wg.Add(1)
+        go func(c <-chan int) {
+            defer wg.Done()
+            for v := range c {
+                out <- v
+            }
+        }(ch)
+    }
+    go func() {
+        wg.Wait()
+        close(out)
+    }()
+    return out
+}
+```
+
+## Context for Cancellation
+
+```go
+func processWithTimeout(ctx context.Context) error {
+    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+    defer cancel()
+
+    select {
+    case result := <-doWork(ctx):
+        return handleResult(result)
+    case <-ctx.Done():
+        return ctx.Err()
+    }
+}
+
+// Propagate context
+func handler(w http.ResponseWriter, r *http.Request) {
+    ctx := r.Context()
+    result, err := service.Process(ctx)  // Pass context down
+    // ...
+}
+```
+
+## Sync Primitives
+
+```go
+// Mutex for shared state
+type Counter struct {
+    mu    sync.Mutex
+    value int
+}
+
+func (c *Counter) Increment() {
+    c.mu.Lock()
+    defer c.mu.Unlock()
+    c.value++
+}
+
+// RWMutex for read-heavy workloads
+type Cache struct {
+    mu   sync.RWMutex
+    data map[string]string
+}
+
+func (c *Cache) Get(key string) (string, bool) {
+    c.mu.RLock()
+    defer c.mu.RUnlock()
+    v, ok := c.data[key]
+    return v, ok
+}
+
+// Once for initialization
+var (
+    instance *Config
+    once     sync.Once
+)
+
+func GetConfig() *Config {
+    once.Do(func() {
+        instance = loadConfig()
+    })
+    return instance
+}
+```

package/rules/golang/core/references/error-handling.md

@@ -0,0 +1,87 @@
+# Error Handling Patterns
+
+## Error Wrapping
+
+```go
+import (
+    "errors"
+    "fmt"
+)
+
+// Wrap errors with context
+func processUser(id string) error {
+    user, err := findUser(id)
+    if err != nil {
+        return fmt.Errorf("processUser: finding user %s: %w", id, err)
+    }
+    return nil
+}
+
+// Check for specific error
+if errors.Is(err, ErrNotFound) {
+    // handle not found
+}
+
+// Extract error type
+var validationErr *ValidationError
+if errors.As(err, &validationErr) {
+    // handle validation error
+}
+```
+
+## Custom Errors
+
+```go
+// Sentinel errors
+var (
+    ErrNotFound     = errors.New("not found")
+    ErrUnauthorized = errors.New("unauthorized")
+)
+
+// Custom error type
+type ValidationError struct {
+    Field   string
+    Message string
+}
+
+func (e *ValidationError) Error() string {
+    return fmt.Sprintf("validation failed: %s - %s", e.Field, e.Message)
+}
+
+// Usage
+return &ValidationError{Field: "email", Message: "invalid format"}
+```
+
+## Error Handling Best Practices
+
+```go
+// 1. Handle errors at the appropriate level
+func handler(w http.ResponseWriter, r *http.Request) {
+    result, err := service.Process(r.Context())
+    if err != nil {
+        switch {
+        case errors.Is(err, ErrNotFound):
+            http.Error(w, "Not found", http.StatusNotFound)
+        case errors.Is(err, ErrUnauthorized):
+            http.Error(w, "Unauthorized", http.StatusUnauthorized)
+        default:
+            log.Printf("unexpected error: %v", err)
+            http.Error(w, "Internal error", http.StatusInternalServerError)
+        }
+        return
+    }
+    json.NewEncoder(w).Encode(result)
+}
+
+// 2. Don't ignore errors
+file, err := os.Open(path)
+if err != nil {
+    return err  // Don't: _ = os.Open(path)
+}
+defer file.Close()
+
+// 3. Panic only for unrecoverable errors
+if config == nil {
+    panic("config is required")  // Startup only
+}
+```

package/rules/golang/echo-framework/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: Echo Framework
+description: High-performance, minimalist Go web framework.
+metadata:
+  labels: [golang, echo, web, framework]
+  triggers:
+    files: ['**/main.go']
+    keywords: [echo, echo.New, echo.Context, e.Start]
+---
+
+# Echo Framework Standards
+
+## Application Setup
+
+```go
+package main
+
+import (
+    "github.com/labstack/echo/v4"
+    "github.com/labstack/echo/v4/middleware"
+)
+
+func main() {
+    e := echo.New()
+
+    // Middleware
+    e.Use(middleware.Logger())
+    e.Use(middleware.Recover())
+    e.Use(middleware.CORS())
+
+    // Routes
+    e.GET("/", homeHandler)
+    e.GET("/users/:id", getUser)
+    e.POST("/users", createUser)
+
+    // Groups
+    api := e.Group("/api/v1")
+    api.GET("/items", listItems)
+
+    e.Logger.Fatal(e.Start(":8080"))
+}
+```
+
+## Handlers
+
+```go
+// Path parameters
+func getUser(c echo.Context) error {
+    id := c.Param("id")
+    user, err := findUser(id)
+    if err != nil {
+        return echo.NewHTTPError(404, "User not found")
+    }
+    return c.JSON(200, user)
+}
+
+// Query parameters
+func listUsers(c echo.Context) error {
+    page := c.QueryParam("page")
+    limit := c.QueryParam("limit")
+    users := fetchUsers(page, limit)
+    return c.JSON(200, users)
+}
+
+// JSON body binding
+type CreateUserRequest struct {
+    Name  string `json:"name" validate:"required"`
+    Email string `json:"email" validate:"required,email"`
+}
+
+func createUser(c echo.Context) error {
+    var req CreateUserRequest
+    if err := c.Bind(&req); err != nil {
+        return echo.NewHTTPError(400, err.Error())
+    }
+    if err := c.Validate(&req); err != nil {
+        return err
+    }
+    user := insertUser(req)
+    return c.JSON(201, user)
+}
+```
+
+## Validation
+
+```go
+import "github.com/go-playground/validator/v10"
+
+type CustomValidator struct {
+    validator *validator.Validate
+}
+
+func (cv *CustomValidator) Validate(i interface{}) error {
+    if err := cv.validator.Struct(i); err != nil {
+        return echo.NewHTTPError(400, err.Error())
+    }
+    return nil
+}
+
+func main() {
+    e := echo.New()
+    e.Validator = &CustomValidator{validator: validator.New()}
+}
+```
+
+## Middleware
+
+```go
+// Built-in middleware
+e.Use(middleware.Logger())
+e.Use(middleware.Recover())
+e.Use(middleware.CORS())
+e.Use(middleware.Gzip())
+e.Use(middleware.RateLimiter(middleware.NewRateLimiterMemoryStore(20)))
+
+// JWT middleware
+e.Use(middleware.JWTWithConfig(middleware.JWTConfig{
+    SigningKey: []byte("secret"),
+    Claims:     &JwtCustomClaims{},
+}))
+
+// Custom middleware
+func authMiddleware(next echo.HandlerFunc) echo.HandlerFunc {
+    return func(c echo.Context) error {
+        token := c.Request().Header.Get("Authorization")
+        if token == "" {
+            return echo.NewHTTPError(401, "Unauthorized")
+        }
+
+        user, err := validateToken(token)
+        if err != nil {
+            return echo.NewHTTPError(401, "Invalid token")
+        }
+
+        c.Set("user", user)
+        return next(c)
+    }
+}
+
+// Apply middleware to group
+api := e.Group("/api", authMiddleware)
+```
+
+## Error Handling
+
+```go
+// Custom HTTP error handler
+e.HTTPErrorHandler = func(err error, c echo.Context) {
+    code := 500
+    message := "Internal Server Error"
+
+    if he, ok := err.(*echo.HTTPError); ok {
+        code = he.Code
+        message = he.Message.(string)
+    }
+
+    c.JSON(code, map[string]string{
+        "error": message,
+    })
+}
+
+// In handlers
+func handler(c echo.Context) error {
+    if notFound {
+        return echo.NewHTTPError(404, "Resource not found")
+    }
+    return c.JSON(200, data)
+}
+```
+
+## Response Types
+
+```go
+// JSON
+c.JSON(200, user)
+
+// String
+c.String(200, "Hello, World!")
+
+// HTML
+c.HTML(200, "<h1>Hello</h1>")
+
+// File
+c.File("path/to/file.pdf")
+
+// Stream
+c.Stream(200, "text/csv", reader)
+
+// Redirect
+c.Redirect(301, "/new-location")
+
+// No Content
+c.NoContent(204)
+```
+
+## Context Values
+
+```go
+// Set value
+c.Set("user", user)
+
+// Get value
+user := c.Get("user").(*User)
+
+// Request context
+ctx := c.Request().Context()
+```
+
+## Best Practices
+
+1. **Validation**: Always validate input with custom validator
+2. **Error handling**: Use `echo.NewHTTPError` for HTTP errors
+3. **Context**: Don't store echo.Context outside request lifecycle
+4. **Middleware order**: Logger first, then Recover, then custom
+5. **Graceful shutdown**: Use `e.Shutdown(ctx)` for graceful shutdown

package/rules/golang/echo-framework/references/REFERENCE.md

@@ -0,0 +1,14 @@
+# Echo Framework References
+
+## References
+
+- [**Routing Patterns**](routing-patterns.md) - Routes, groups, path parameters
+- [**Middleware**](middleware-patterns.md) - Built-in and custom middleware
+
+## Quick Checks
+
+- [ ] Use route groups for versioning
+- [ ] Apply middleware at appropriate levels
+- [ ] Custom context for request-scoped data
+- [ ] Structured error handling with HTTPError
+- [ ] Graceful shutdown handling

package/rules/golang/echo-framework/references/middleware-patterns.md

@@ -0,0 +1,141 @@
+# Echo Middleware Patterns
+
+## Built-in Middleware
+
+```go
+import (
+    "github.com/labstack/echo/v4"
+    "github.com/labstack/echo/v4/middleware"
+)
+
+func main() {
+    e := echo.New()
+
+    // Logger
+    e.Use(middleware.Logger())
+
+    // Recover from panics
+    e.Use(middleware.Recover())
+
+    // CORS
+    e.Use(middleware.CORSWithConfig(middleware.CORSConfig{
+        AllowOrigins: []string{"https://example.com"},
+        AllowMethods: []string{http.MethodGet, http.MethodPost},
+    }))
+
+    // Request ID
+    e.Use(middleware.RequestID())
+
+    // Rate limiter
+    e.Use(middleware.RateLimiter(middleware.NewRateLimiterMemoryStore(20)))
+
+    // Gzip compression
+    e.Use(middleware.Gzip())
+}
+```
+
+## Custom Middleware
+
+```go
+// Timing middleware
+func TimingMiddleware(next echo.HandlerFunc) echo.HandlerFunc {
+    return func(c echo.Context) error {
+        start := time.Now()
+        
+        err := next(c)
+        
+        duration := time.Since(start)
+        c.Response().Header().Set("X-Response-Time", duration.String())
+        
+        return err
+    }
+}
+
+// Auth middleware
+func AuthMiddleware(next echo.HandlerFunc) echo.HandlerFunc {
+    return func(c echo.Context) error {
+        token := c.Request().Header.Get("Authorization")
+        if token == "" {
+            return echo.NewHTTPError(http.StatusUnauthorized, "missing token")
+        }
+
+        // Validate token
+        claims, err := validateToken(token)
+        if err != nil {
+            return echo.NewHTTPError(http.StatusUnauthorized, "invalid token")
+        }
+
+        // Store in context
+        c.Set("user", claims.UserID)
+        
+        return next(c)
+    }
+}
+
+// Usage
+e.GET("/protected", handler, AuthMiddleware)
+```
+
+## Middleware with Config
+
+```go
+type AuthConfig struct {
+    Skipper    middleware.Skipper
+    TokenLookup string
+    AuthScheme  string
+}
+
+func AuthWithConfig(config AuthConfig) echo.MiddlewareFunc {
+    return func(next echo.HandlerFunc) echo.HandlerFunc {
+        return func(c echo.Context) error {
+            if config.Skipper != nil && config.Skipper(c) {
+                return next(c)
+            }
+            
+            // Auth logic using config...
+            
+            return next(c)
+        }
+    }
+}
+
+// Skip auth for certain paths
+e.Use(AuthWithConfig(AuthConfig{
+    Skipper: func(c echo.Context) bool {
+        return c.Path() == "/health" || c.Path() == "/login"
+    },
+}))
+```
+
+## JWT Authentication
+
+```go
+import "github.com/labstack/echo-jwt/v4"
+
+func main() {
+    e := echo.New()
+
+    // JWT middleware
+    config := echojwt.Config{
+        SigningKey: []byte("secret"),
+        NewClaimsFunc: func(c echo.Context) jwt.Claims {
+            return new(JwtCustomClaims)
+        },
+    }
+
+    r := e.Group("/api")
+    r.Use(echojwt.WithConfig(config))
+
+    r.GET("/users", func(c echo.Context) error {
+        token := c.Get("user").(*jwt.Token)
+        claims := token.Claims.(*JwtCustomClaims)
+        return c.JSON(http.StatusOK, claims)
+    })
+}
+
+type JwtCustomClaims struct {
+    UserID string `json:"user_id"`
+    Role   string `json:"role"`
+    jwt.RegisteredClaims
+}
+```

package/rules/golang/echo-framework/references/routing-patterns.md

@@ -0,0 +1,140 @@
+# Echo Routing Patterns
+
+## Basic Routing
+
+```go
+import (
+    "net/http"
+    "github.com/labstack/echo/v4"
+)
+
+func main() {
+    e := echo.New()
+
+    // Basic routes
+    e.GET("/users", listUsers)
+    e.POST("/users", createUser)
+    e.GET("/users/:id", getUser)
+    e.PUT("/users/:id", updateUser)
+    e.DELETE("/users/:id", deleteUser)
+
+    e.Logger.Fatal(e.Start(":8080"))
+}
+
+// Handler with path parameter
+func getUser(c echo.Context) error {
+    id := c.Param("id")
+    return c.JSON(http.StatusOK, map[string]string{"id": id})
+}
+
+// Query parameters
+func listUsers(c echo.Context) error {
+    page := c.QueryParam("page")
+    limit := c.QueryParam("limit")
+    return c.JSON(http.StatusOK, map[string]string{
+        "page":  page,
+        "limit": limit,
+    })
+}
+```
+
+## Route Groups
+
+```go
+func main() {
+    e := echo.New()
+
+    // API versioning
+    v1 := e.Group("/api/v1")
+    {
+        v1.GET("/users", listUsersV1)
+        v1.POST("/users", createUserV1)
+    }
+
+    v2 := e.Group("/api/v2")
+    {
+        v2.GET("/users", listUsersV2)
+    }
+
+    // Group with middleware
+    admin := e.Group("/admin", middleware.BasicAuth(validateAdmin))
+    {
+        admin.GET("/stats", getStats)
+        admin.POST("/config", updateConfig)
+    }
+}
+```
+
+## Request Binding
+
+```go
+type CreateUserRequest struct {
+    Name  string `json:"name" validate:"required"`
+    Email string `json:"email" validate:"required,email"`
+    Age   int    `json:"age" validate:"gte=0,lte=130"`
+}
+
+func createUser(c echo.Context) error {
+    req := new(CreateUserRequest)
+    if err := c.Bind(req); err != nil {
+        return echo.NewHTTPError(http.StatusBadRequest, err.Error())
+    }
+
+    // Validate
+    if err := c.Validate(req); err != nil {
+        return err
+    }
+
+    // Process...
+    return c.JSON(http.StatusCreated, req)
+}
+
+// Setup validator
+func main() {
+    e := echo.New()
+    e.Validator = &CustomValidator{validator: validator.New()}
+}
+
+type CustomValidator struct {
+    validator *validator.Validate
+}
+
+func (cv *CustomValidator) Validate(i interface{}) error {
+    if err := cv.validator.Struct(i); err != nil {
+        return echo.NewHTTPError(http.StatusBadRequest, err.Error())
+    }
+    return nil
+}
+```
+
+## Error Handling
+
+```go
+// Custom HTTP error handler
+e.HTTPErrorHandler = func(err error, c echo.Context) {
+    code := http.StatusInternalServerError
+    message := "Internal Server Error"
+
+    if he, ok := err.(*echo.HTTPError); ok {
+        code = he.Code
+        message = he.Message.(string)
+    }
+
+    c.JSON(code, map[string]string{
+        "error": message,
+    })
+}
+
+// In handlers
+func getUser(c echo.Context) error {
+    id := c.Param("id")
+    user, err := userService.FindByID(id)
+    if err != nil {
+        if errors.Is(err, ErrNotFound) {
+            return echo.NewHTTPError(http.StatusNotFound, "user not found")
+        }
+        return echo.NewHTTPError(http.StatusInternalServerError, err.Error())
+    }
+    return c.JSON(http.StatusOK, user)
+}
+```