@ngxtm/devkit 3.4.0 → 3.4.1

package/rules/golang/chi-router/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: Chi Router
+description: Lightweight, composable Go HTTP router built on net/http.
+metadata:
+  labels: [golang, chi, router, http]
+  triggers:
+    files: ['**/main.go', '**/routes.go']
+    keywords: [chi, chi.NewRouter, chi.Router, r.Route]
+---
+
+# Chi Router Standards
+
+## Router Setup
+
+```go
+package main
+
+import (
+    "net/http"
+    "github.com/go-chi/chi/v5"
+    "github.com/go-chi/chi/v5/middleware"
+)
+
+func main() {
+    r := chi.NewRouter()
+
+    // Middleware
+    r.Use(middleware.Logger)
+    r.Use(middleware.Recoverer)
+    r.Use(middleware.RequestID)
+    r.Use(middleware.RealIP)
+
+    // Routes
+    r.Get("/", homeHandler)
+    r.Get("/users/{id}", getUser)
+    r.Post("/users", createUser)
+
+    // Sub-routers
+    r.Route("/api/v1", func(r chi.Router) {
+        r.Get("/items", listItems)
+        r.Post("/items", createItem)
+    })
+
+    http.ListenAndServe(":8080", r)
+}
+```
+
+## Handlers
+
+```go
+// Path parameters
+func getUser(w http.ResponseWriter, r *http.Request) {
+    id := chi.URLParam(r, "id")
+    user, err := findUser(id)
+    if err != nil {
+        http.Error(w, "Not found", http.StatusNotFound)
+        return
+    }
+    json.NewEncoder(w).Encode(user)
+}
+
+// Query parameters
+func listUsers(w http.ResponseWriter, r *http.Request) {
+    page := r.URL.Query().Get("page")
+    limit := r.URL.Query().Get("limit")
+    users := fetchUsers(page, limit)
+    json.NewEncoder(w).Encode(users)
+}
+
+// JSON body
+func createUser(w http.ResponseWriter, r *http.Request) {
+    var req CreateUserRequest
+    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+        http.Error(w, err.Error(), http.StatusBadRequest)
+        return
+    }
+    user := insertUser(req)
+    w.WriteHeader(http.StatusCreated)
+    json.NewEncoder(w).Encode(user)
+}
+```
+
+## Middleware
+
+```go
+// Built-in middleware
+r.Use(middleware.Logger)          // Logs requests
+r.Use(middleware.Recoverer)       // Panic recovery
+r.Use(middleware.RequestID)       // Request ID header
+r.Use(middleware.RealIP)          // Real IP from headers
+r.Use(middleware.Compress(5))     // Gzip compression
+r.Use(middleware.Timeout(60 * time.Second))
+
+// Custom middleware
+func authMiddleware(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        token := r.Header.Get("Authorization")
+        if token == "" {
+            http.Error(w, "Unauthorized", http.StatusUnauthorized)
+            return
+        }
+
+        user, err := validateToken(token)
+        if err != nil {
+            http.Error(w, "Invalid token", http.StatusUnauthorized)
+            return
+        }
+
+        ctx := context.WithValue(r.Context(), "user", user)
+        next.ServeHTTP(w, r.WithContext(ctx))
+    })
+}
+
+// Apply to group
+r.Route("/api", func(r chi.Router) {
+    r.Use(authMiddleware)
+    r.Get("/protected", protectedHandler)
+})
+```
+
+## Route Groups & Nesting
+
+```go
+r.Route("/api/v1", func(r chi.Router) {
+    // All routes here prefixed with /api/v1
+
+    r.Route("/users", func(r chi.Router) {
+        r.Get("/", listUsers)
+        r.Post("/", createUser)
+
+        r.Route("/{id}", func(r chi.Router) {
+            r.Get("/", getUser)
+            r.Put("/", updateUser)
+            r.Delete("/", deleteUser)
+        })
+    })
+
+    r.Route("/items", func(r chi.Router) {
+        r.Get("/", listItems)
+    })
+})
+```
+
+## Mount Sub-Routers
+
+```go
+func main() {
+    r := chi.NewRouter()
+    r.Mount("/api/v1", apiRouter())
+    r.Mount("/admin", adminRouter())
+    http.ListenAndServe(":8080", r)
+}
+
+func apiRouter() chi.Router {
+    r := chi.NewRouter()
+    r.Get("/users", listUsers)
+    r.Post("/users", createUser)
+    return r
+}
+
+func adminRouter() chi.Router {
+    r := chi.NewRouter()
+    r.Use(adminAuthMiddleware)
+    r.Get("/stats", getStats)
+    return r
+}
+```
+
+## Context Values
+
+```go
+// Set in middleware
+ctx := context.WithValue(r.Context(), "user", user)
+next.ServeHTTP(w, r.WithContext(ctx))
+
+// Get in handler
+user := r.Context().Value("user").(*User)
+
+// Type-safe context keys
+type contextKey string
+const userKey contextKey = "user"
+
+ctx := context.WithValue(r.Context(), userKey, user)
+user := r.Context().Value(userKey).(*User)
+```
+
+## Response Helpers
+
+```go
+import "github.com/go-chi/render"
+
+type UserResponse struct {
+    ID    int    `json:"id"`
+    Name  string `json:"name"`
+}
+
+func (u *UserResponse) Render(w http.ResponseWriter, r *http.Request) error {
+    return nil
+}
+
+func getUser(w http.ResponseWriter, r *http.Request) {
+    user := &UserResponse{ID: 1, Name: "John"}
+    render.Render(w, r, user)
+}
+
+// Error response
+func ErrNotFound(w http.ResponseWriter, r *http.Request, err error) {
+    render.Status(r, http.StatusNotFound)
+    render.JSON(w, r, map[string]string{"error": err.Error()})
+}
+```
+
+## Best Practices
+
+1. **Standard library**: Chi uses net/http, fully compatible with standard handlers
+2. **Composition**: Use `r.Route()` for grouping, `r.Mount()` for sub-routers
+3. **Middleware order**: Apply in order of execution (outer to inner)
+4. **Context**: Use typed keys for context values
+5. **Testing**: Use `httptest` - Chi handlers are standard `http.Handler`

package/rules/golang/chi-router/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# Chi Router References
+
+## References
+
+- [**Routing Patterns**](routing-patterns.md) - Routes, middleware, subrouters
+
+## Quick Checks
+
+- [ ] Lightweight, idiomatic Go router
+- [ ] Middleware chain pattern
+- [ ] URL parameters via chi.URLParam
+- [ ] Subrouters for modular code
+- [ ] Compatible with net/http

package/rules/golang/chi-router/references/routing-patterns.md

@@ -0,0 +1,205 @@
+# Chi Routing Patterns
+
+## Basic Setup
+
+```go
+import (
+    "net/http"
+    "github.com/go-chi/chi/v5"
+    "github.com/go-chi/chi/v5/middleware"
+)
+
+func main() {
+    r := chi.NewRouter()
+
+    // Built-in middleware
+    r.Use(middleware.Logger)
+    r.Use(middleware.Recoverer)
+    r.Use(middleware.RequestID)
+
+    // Routes
+    r.Get("/", func(w http.ResponseWriter, r *http.Request) {
+        w.Write([]byte("Hello World!"))
+    })
+
+    r.Get("/users/{id}", getUser)
+    r.Post("/users", createUser)
+
+    http.ListenAndServe(":3000", r)
+}
+```
+
+## Handlers
+
+```go
+import (
+    "encoding/json"
+    "net/http"
+    "github.com/go-chi/chi/v5"
+)
+
+func getUser(w http.ResponseWriter, r *http.Request) {
+    id := chi.URLParam(r, "id")
+    
+    user := User{ID: id, Name: "John"}
+    
+    w.Header().Set("Content-Type", "application/json")
+    json.NewEncoder(w).Encode(user)
+}
+
+func createUser(w http.ResponseWriter, r *http.Request) {
+    var user User
+    if err := json.NewDecoder(r.Body).Decode(&user); err != nil {
+        http.Error(w, err.Error(), http.StatusBadRequest)
+        return
+    }
+    
+    w.WriteHeader(http.StatusCreated)
+    json.NewEncoder(w).Encode(user)
+}
+```
+
+## Route Groups
+
+```go
+func main() {
+    r := chi.NewRouter()
+
+    // API routes
+    r.Route("/api", func(r chi.Router) {
+        r.Use(apiMiddleware)
+        
+        r.Route("/v1", func(r chi.Router) {
+            r.Get("/users", listUsersV1)
+            r.Post("/users", createUserV1)
+            
+            r.Route("/users/{id}", func(r chi.Router) {
+                r.Get("/", getUser)
+                r.Put("/", updateUser)
+                r.Delete("/", deleteUser)
+            })
+        })
+    })
+
+    // Admin routes with auth
+    r.Group(func(r chi.Router) {
+        r.Use(authMiddleware)
+        r.Get("/admin/stats", getStats)
+    })
+}
+```
+
+## Subrouters
+
+```go
+// users.go
+func UsersRouter() chi.Router {
+    r := chi.NewRouter()
+    
+    r.Get("/", listUsers)
+    r.Post("/", createUser)
+    r.Get("/{id}", getUser)
+    r.Put("/{id}", updateUser)
+    r.Delete("/{id}", deleteUser)
+    
+    return r
+}
+
+// orders.go
+func OrdersRouter() chi.Router {
+    r := chi.NewRouter()
+    r.Get("/", listOrders)
+    r.Post("/", createOrder)
+    return r
+}
+
+// main.go
+func main() {
+    r := chi.NewRouter()
+    
+    r.Mount("/users", UsersRouter())
+    r.Mount("/orders", OrdersRouter())
+    
+    http.ListenAndServe(":3000", r)
+}
+```
+
+## Middleware
+
+```go
+// Custom middleware
+func AuthMiddleware(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        token := r.Header.Get("Authorization")
+        if token == "" {
+            http.Error(w, "Unauthorized", http.StatusUnauthorized)
+            return
+        }
+        
+        // Validate token, add user to context
+        ctx := context.WithValue(r.Context(), "user", userID)
+        next.ServeHTTP(w, r.WithContext(ctx))
+    })
+}
+
+// Request-scoped middleware
+func UserCtx(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        id := chi.URLParam(r, "id")
+        user, err := findUser(id)
+        if err != nil {
+            http.Error(w, "Not Found", http.StatusNotFound)
+            return
+        }
+        ctx := context.WithValue(r.Context(), "user", user)
+        next.ServeHTTP(w, r.WithContext(ctx))
+    })
+}
+
+// Usage
+r.Route("/users/{id}", func(r chi.Router) {
+    r.Use(UserCtx)
+    r.Get("/", getUser)    // User available in context
+    r.Put("/", updateUser)
+})
+```
+
+## Built-in Middleware
+
+```go
+import "github.com/go-chi/chi/v5/middleware"
+
+r.Use(middleware.RequestID)       // X-Request-ID header
+r.Use(middleware.RealIP)          // X-Real-IP, X-Forwarded-For
+r.Use(middleware.Logger)          // Request logging
+r.Use(middleware.Recoverer)       // Panic recovery
+r.Use(middleware.Timeout(60 * time.Second))
+r.Use(middleware.Throttle(100))   // Rate limiting
+r.Use(middleware.Compress(5))     // Gzip compression
+r.Use(middleware.AllowContentType("application/json"))
+```
+
+## Pattern Matching
+
+```go
+// Basic pattern
+r.Get("/users/{id}", handler)
+
+// Regex constraint
+r.Get("/articles/{date:\\d{4}-\\d{2}-\\d{2}}", handler)
+
+// Catch-all
+r.Get("/files/*", handler) // r.URL.Path contains full path
+
+// Not found handler
+r.NotFound(func(w http.ResponseWriter, r *http.Request) {
+    w.WriteHeader(http.StatusNotFound)
+    w.Write([]byte("Not found"))
+})
+
+// Method not allowed
+r.MethodNotAllowed(func(w http.ResponseWriter, r *http.Request) {
+    w.WriteHeader(http.StatusMethodNotAllowed)
+    w.Write([]byte("Method not allowed"))
+})
+```

package/rules/golang/cobra-cli/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: Cobra CLI
+description: Modern CLI framework used by kubectl, docker, and more.
+metadata:
+  labels: [golang, cobra, cli, command]
+  triggers:
+    files: ['cmd/**/*.go', '**/root.go']
+    keywords: [cobra, Command, RunE, Flags, PersistentFlags]
+---
+
+# Cobra CLI Standards
+
+## Basic Setup
+
+```go
+// cmd/root.go
+package cmd
+
+import (
+    "os"
+    "github.com/spf13/cobra"
+)
+
+var rootCmd = &cobra.Command{
+    Use:   "myapp",
+    Short: "A brief description",
+    Long:  `A longer description...`,
+}
+
+func Execute() {
+    if err := rootCmd.Execute(); err != nil {
+        os.Exit(1)
+    }
+}
+
+func init() {
+    rootCmd.PersistentFlags().StringP("config", "c", "", "config file")
+    rootCmd.PersistentFlags().BoolP("verbose", "v", false, "verbose output")
+}
+```
+
+```go
+// main.go
+package main
+
+import "myapp/cmd"
+
+func main() {
+    cmd.Execute()
+}
+```
+
+## Subcommands
+
+```go
+// cmd/serve.go
+var serveCmd = &cobra.Command{
+    Use:   "serve",
+    Short: "Start the server",
+    RunE: func(cmd *cobra.Command, args []string) error {
+        port, _ := cmd.Flags().GetInt("port")
+        return startServer(port)
+    },
+}
+
+func init() {
+    rootCmd.AddCommand(serveCmd)
+    serveCmd.Flags().IntP("port", "p", 8080, "server port")
+}
+
+// cmd/db.go - nested commands
+var dbCmd = &cobra.Command{
+    Use:   "db",
+    Short: "Database operations",
+}
+
+var dbMigrateCmd = &cobra.Command{
+    Use:   "migrate",
+    Short: "Run migrations",
+    RunE: func(cmd *cobra.Command, args []string) error {
+        return runMigrations()
+    },
+}
+
+func init() {
+    rootCmd.AddCommand(dbCmd)
+    dbCmd.AddCommand(dbMigrateCmd)
+}
+```
+
+## Flags
+
+```go
+var cfgFile string
+var verbose bool
+
+func init() {
+    // Persistent flags (inherited by subcommands)
+    rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file")
+    rootCmd.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "verbose")
+
+    // Local flags (only for this command)
+    serveCmd.Flags().IntP("port", "p", 8080, "port number")
+    serveCmd.Flags().StringSlice("hosts", []string{}, "allowed hosts")
+
+    // Required flags
+    serveCmd.MarkFlagRequired("port")
+
+    // Flag groups
+    serveCmd.MarkFlagsRequiredTogether("cert", "key")
+    serveCmd.MarkFlagsMutuallyExclusive("json", "yaml")
+}
+```
+
+## Arguments
+
+```go
+var echoCmd = &cobra.Command{
+    Use:   "echo [message]",
+    Short: "Echo a message",
+    Args:  cobra.ExactArgs(1),  // Require exactly 1 arg
+    RunE: func(cmd *cobra.Command, args []string) error {
+        fmt.Println(args[0])
+        return nil
+    },
+}
+
+// Argument validators
+cobra.NoArgs           // No arguments allowed
+cobra.ExactArgs(n)     // Exactly n arguments
+cobra.MinimumNArgs(n)  // At least n arguments
+cobra.MaximumNArgs(n)  // At most n arguments
+cobra.RangeArgs(m, n)  // Between m and n arguments
+
+// Custom validation
+Args: func(cmd *cobra.Command, args []string) error {
+    if len(args) < 1 {
+        return errors.New("requires at least one argument")
+    }
+    return nil
+},
+```
+
+## Viper Integration
+
+```go
+import (
+    "github.com/spf13/cobra"
+    "github.com/spf13/viper"
+)
+
+func init() {
+    cobra.OnInitialize(initConfig)
+    rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file")
+
+    // Bind flags to viper
+    rootCmd.PersistentFlags().String("database-url", "", "database URL")
+    viper.BindPFlag("database.url", rootCmd.PersistentFlags().Lookup("database-url"))
+}
+
+func initConfig() {
+    if cfgFile != "" {
+        viper.SetConfigFile(cfgFile)
+    } else {
+        viper.SetConfigName("config")
+        viper.SetConfigType("yaml")
+        viper.AddConfigPath(".")
+        viper.AddConfigPath("$HOME/.myapp")
+    }
+
+    viper.AutomaticEnv()
+    viper.ReadInConfig()
+}
+```
+
+## Pre/Post Hooks
+
+```go
+var rootCmd = &cobra.Command{
+    Use: "myapp",
+    PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
+        // Runs before any command
+        return initLogger()
+    },
+    PersistentPostRunE: func(cmd *cobra.Command, args []string) error {
+        // Runs after any command
+        return cleanup()
+    },
+}
+
+var serveCmd = &cobra.Command{
+    Use: "serve",
+    PreRunE: func(cmd *cobra.Command, args []string) error {
+        // Runs before this command only
+        return validateConfig()
+    },
+    RunE: func(cmd *cobra.Command, args []string) error {
+        return serve()
+    },
+}
+```
+
+## Shell Completions
+
+```go
+// Auto-generated completions
+rootCmd.GenBashCompletionFile("completions/myapp.bash")
+rootCmd.GenZshCompletionFile("completions/myapp.zsh")
+rootCmd.GenFishCompletionFile("completions/myapp.fish")
+
+// Custom completions
+var userCmd = &cobra.Command{
+    Use: "user [username]",
+    ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+        users := fetchUsernames()
+        return users, cobra.ShellCompDirectiveNoFileComp
+    },
+}
+```
+
+## Best Practices
+
+1. **Structure**: One file per command in `cmd/` directory
+2. **Errors**: Use `RunE` and return errors, don't `os.Exit`
+3. **Flags**: Use persistent flags for shared options
+4. **Viper**: Integrate for config file support
+5. **Help**: Write clear Use, Short, and Long descriptions

package/rules/golang/cobra-cli/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# Cobra CLI References
+
+## References
+
+- [**Command Patterns**](command-patterns.md) - Commands, flags, subcommands
+
+## Quick Checks
+
+- [ ] Root command for main entry
+- [ ] Subcommands for features
+- [ ] Persistent flags for global options
+- [ ] PreRun/PostRun hooks
+- [ ] Automatic help generation