@ngxtm/devkit 3.4.0 → 3.4.1

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)
+}
+```