@mytechtoday/augment-extensions 1.4.0 → 1.5.0

package/augment-extensions/coding-standards/go/rules/web/routing.md

@@ -0,0 +1,251 @@
+# Go Web Services - Routing Patterns
+
+## Overview
+
+Routing is fundamental to web services, mapping HTTP requests to handlers. This document defines best practices for implementing routing in Go web services.
+
+## Core Principles
+
+1. **RESTful Design**: Follow REST principles for resource-based APIs
+2. **URL Parameters**: Use path parameters for resource identifiers
+3. **Query Parameters**: Use query strings for filtering and pagination
+4. **Method Routing**: Route based on HTTP methods (GET, POST, PUT, DELETE)
+5. **Versioning**: Support API versioning through URLs or headers
+
+## Rules
+
+### GOL.3.1.3.1: Use Established Routing Libraries
+
+**Rule**: Use proven routing libraries like `gorilla/mux`, `chi`, or `echo` for complex routing needs.
+
+**Severity**: WARNING
+
+**Rationale**: Standard library `http.ServeMux` is limited; established libraries provide better features.
+
+**✅ Good - Using chi**:
+```go
+import "github.com/go-chi/chi/v5"
+
+func setupRoutes() http.Handler {
+    r := chi.NewRouter()
+    
+    // Middleware
+    r.Use(middleware.Logger)
+    r.Use(middleware.Recoverer)
+    
+    // Routes
+    r.Get("/health", handleHealth)
+    
+    r.Route("/api/v1", func(r chi.Router) {
+        r.Use(authMiddleware)
+        
+        r.Route("/users", func(r chi.Router) {
+            r.Get("/", listUsers)           // GET /api/v1/users
+            r.Post("/", createUser)          // POST /api/v1/users
+            r.Get("/{id}", getUser)          // GET /api/v1/users/123
+            r.Put("/{id}", updateUser)       // PUT /api/v1/users/123
+            r.Delete("/{id}", deleteUser)    // DELETE /api/v1/users/123
+        })
+    })
+    
+    return r
+}
+```
+
+**✅ Good - Using gorilla/mux**:
+```go
+import "github.com/gorilla/mux"
+
+func setupRoutes() http.Handler {
+    r := mux.NewRouter()
+    
+    // API v1 routes
+    api := r.PathPrefix("/api/v1").Subrouter()
+    api.Use(authMiddleware)
+    
+    // User routes
+    api.HandleFunc("/users", listUsers).Methods("GET")
+    api.HandleFunc("/users", createUser).Methods("POST")
+    api.HandleFunc("/users/{id}", getUser).Methods("GET")
+    api.HandleFunc("/users/{id}", updateUser).Methods("PUT")
+    api.HandleFunc("/users/{id}", deleteUser).Methods("DELETE")
+    
+    return r
+}
+```
+
+### GOL.3.1.3.2: Follow RESTful Resource Naming
+
+**Rule**: Use plural nouns for resources and standard HTTP methods for operations.
+
+**Severity**: WARNING
+
+**Rationale**: Consistent RESTful design improves API usability and predictability.
+
+**RESTful Patterns**:
+- `GET /users` - List all users
+- `GET /users/{id}` - Get specific user
+- `POST /users` - Create new user
+- `PUT /users/{id}` - Update entire user
+- `PATCH /users/{id}` - Partial update user
+- `DELETE /users/{id}` - Delete user
+
+**✅ Good**:
+```go
+r.Route("/api/v1/users", func(r chi.Router) {
+    r.Get("/", listUsers)              // List users
+    r.Post("/", createUser)            // Create user
+    r.Get("/{id}", getUser)            // Get user by ID
+    r.Put("/{id}", updateUser)         // Update user
+    r.Delete("/{id}", deleteUser)      // Delete user
+    
+    // Nested resources
+    r.Get("/{id}/posts", getUserPosts) // Get user's posts
+})
+```
+
+**❌ Bad**:
+```go
+// Non-RESTful, verb-based URLs
+r.Get("/getUser", getUser)
+r.Post("/createUser", createUser)
+r.Post("/deleteUser", deleteUser)
+```
+
+### GOL.3.1.3.3: Extract URL Parameters Safely
+
+**Rule**: Always validate URL parameters before use.
+
+**Severity**: ERROR
+
+**Rationale**: Invalid parameters can cause panics or security vulnerabilities.
+
+**✅ Good**:
+```go
+func getUser(w http.ResponseWriter, r *http.Request) {
+    // Extract parameter
+    idStr := chi.URLParam(r, "id")
+    if idStr == "" {
+        http.Error(w, "Missing user ID", http.StatusBadRequest)
+        return
+    }
+    
+    // Validate and convert
+    id, err := strconv.ParseInt(idStr, 10, 64)
+    if err != nil {
+        http.Error(w, "Invalid user ID", http.StatusBadRequest)
+        return
+    }
+    
+    // Use validated parameter
+    user, err := getUserByID(r.Context(), id)
+    if err != nil {
+        if errors.Is(err, ErrNotFound) {
+            http.Error(w, "User not found", http.StatusNotFound)
+            return
+        }
+        http.Error(w, "Internal error", http.StatusInternalServerError)
+        return
+    }
+    
+    json.NewEncoder(w).Encode(user)
+}
+```
+
+### GOL.3.1.3.4: Implement API Versioning
+
+**Rule**: Version APIs using URL path prefixes (e.g., `/api/v1`, `/api/v2`).
+
+**Severity**: WARNING
+
+**Rationale**: Versioning enables backward compatibility and gradual migration.
+
+**✅ Good**:
+```go
+func setupRoutes() http.Handler {
+    r := chi.NewRouter()
+    
+    // Version 1 API
+    r.Route("/api/v1", func(r chi.Router) {
+        r.Get("/users", listUsersV1)
+        r.Get("/users/{id}", getUserV1)
+    })
+    
+    // Version 2 API with breaking changes
+    r.Route("/api/v2", func(r chi.Router) {
+        r.Get("/users", listUsersV2)
+        r.Get("/users/{id}", getUserV2)
+    })
+    
+    return r
+}
+```
+
+### GOL.3.1.3.5: Use Query Parameters for Filtering
+
+**Rule**: Use query parameters for filtering, sorting, and pagination.
+
+**Severity**: INFO
+
+**✅ Good**:
+```go
+func listUsers(w http.ResponseWriter, r *http.Request) {
+    ctx := r.Context()
+    
+    // Parse query parameters
+    query := r.URL.Query()
+    
+    // Pagination
+    page, _ := strconv.Atoi(query.Get("page"))
+    if page < 1 {
+        page = 1
+    }
+    
+    limit, _ := strconv.Atoi(query.Get("limit"))
+    if limit < 1 || limit > 100 {
+        limit = 20
+    }
+    
+    // Filtering
+    role := query.Get("role")
+    status := query.Get("status")
+    
+    // Sorting
+    sortBy := query.Get("sort")
+    if sortBy == "" {
+        sortBy = "created_at"
+    }
+    
+    // Build filter
+    filter := UserFilter{
+        Page:   page,
+        Limit:  limit,
+        Role:   role,
+        Status: status,
+        SortBy: sortBy,
+    }
+    
+    users, total, err := listUsersWithFilter(ctx, filter)
+    if err != nil {
+        http.Error(w, "Internal error", http.StatusInternalServerError)
+        return
+    }
+    
+    // Return paginated response
+    response := PaginatedResponse{
+        Data:  users,
+        Total: total,
+        Page:  page,
+        Limit: limit,
+    }
+    
+    json.NewEncoder(w).Encode(response)
+}
+```
+
+## References
+
+- [RESTful API Design](https://restfulapi.net/)
+- [chi router](https://github.com/go-chi/chi)
+- [gorilla/mux](https://github.com/gorilla/mux)
+

package/augment-extensions/coding-standards/go/templates/prompts/api.md

@@ -0,0 +1,160 @@
+# REST API Development Go Application AI Template
+
+## Context
+
+You are building a RESTful API in Go with proper versioning, rate limiting, pagination, and error handling.
+
+## Key Requirements
+
+### REST API Design
+- Use appropriate HTTP methods (GET, POST, PUT, PATCH, DELETE)
+- Return correct HTTP status codes for different scenarios
+- Implement consistent error response format
+- Support pagination for collection endpoints
+- Implement filtering and sorting query parameters
+
+### API Versioning
+- Use URL path versioning (/api/v1, /api/v2)
+- Maintain backward compatibility for old versions
+- Document version deprecation with headers
+- Support content negotiation as alternative
+- Only version breaking changes, not additions
+
+### Rate Limiting
+- Implement token bucket algorithm for smooth limiting
+- Return rate limit headers (X-RateLimit-*)
+- Apply different limits for different endpoints
+- Support API key-based rate limiting with tiers
+- Use Redis for distributed rate limiting
+
+### Error Handling
+- Return structured error responses with details
+- Include error codes for programmatic handling
+- Provide helpful error messages
+- Log errors with appropriate context
+
+## Code Structure
+
+```go
+type API struct {
+    router      *mux.Router
+    rateLimiter *RateLimiter
+}
+
+type ErrorResponse struct {
+    Error   string `json:"error"`
+    Message string `json:"message"`
+    Code    string `json:"code,omitempty"`
+}
+
+type PaginatedResponse struct {
+    Data       interface{} `json:"data"`
+    Page       int         `json:"page"`
+    PageSize   int         `json:"page_size"`
+    TotalItems int         `json:"total_items"`
+}
+```
+
+## Example Patterns
+
+### REST Endpoints
+```go
+func SetupRoutes(r *mux.Router) {
+    v1 := r.PathPrefix("/api/v1").Subrouter()
+    v1.HandleFunc("/users", CreateUser).Methods("POST")
+    v1.HandleFunc("/users", ListUsers).Methods("GET")
+    v1.HandleFunc("/users/{id}", GetUser).Methods("GET")
+    v1.HandleFunc("/users/{id}", UpdateUser).Methods("PUT")
+    v1.HandleFunc("/users/{id}", DeleteUser).Methods("DELETE")
+}
+```
+
+### Error Handling
+```go
+func CreateUser(w http.ResponseWriter, r *http.Request) {
+    var user User
+    if err := json.NewDecoder(r.Body).Decode(&user); err != nil {
+        writeError(w, http.StatusBadRequest, "Invalid request body")
+        return
+    }
+    
+    if err := validateUser(&user); err != nil {
+        writeError(w, http.StatusUnprocessableEntity, err.Error())
+        return
+    }
+    
+    writeJSON(w, http.StatusCreated, user)
+}
+```
+
+### Pagination
+```go
+func ListUsers(w http.ResponseWriter, r *http.Request) {
+    page, _ := strconv.Atoi(r.URL.Query().Get("page"))
+    if page < 1 {
+        page = 1
+    }
+    
+    pageSize, _ := strconv.Atoi(r.URL.Query().Get("page_size"))
+    if pageSize < 1 || pageSize > 100 {
+        pageSize = 20
+    }
+    
+    users, total, _ := db.ListUsers(page, pageSize)
+    
+    response := PaginatedResponse{
+        Data:       users,
+        Page:       page,
+        PageSize:   pageSize,
+        TotalItems: total,
+        TotalPages: (total + pageSize - 1) / pageSize,
+    }
+    
+    writeJSON(w, http.StatusOK, response)
+}
+```
+
+### Rate Limiting
+```go
+func RateLimitMiddleware(limiter *RateLimiter) func(http.Handler) http.Handler {
+    return func(next http.Handler) http.Handler {
+        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+            key := getClientKey(r)
+            l := limiter.GetLimiter(key)
+            
+            if !l.Allow() {
+                w.Header().Set("X-RateLimit-Limit", "100")
+                w.Header().Set("X-RateLimit-Remaining", "0")
+                w.Header().Set("Retry-After", "60")
+                writeError(w, http.StatusTooManyRequests, "Rate limit exceeded")
+                return
+            }
+            
+            next.ServeHTTP(w, r)
+        })
+    }
+}
+```
+
+## Best Practices
+
+1. **Consistency**: Use consistent naming and response formats
+2. **Documentation**: Provide OpenAPI/Swagger documentation
+3. **Security**: Implement authentication and authorization
+4. **Validation**: Validate all inputs thoroughly
+5. **Testing**: Write integration tests for all endpoints
+
+## Common Pitfalls to Avoid
+
+- ❌ Not returning appropriate status codes
+- ❌ Missing pagination on collection endpoints
+- ❌ Inconsistent error response format
+- ❌ Not implementing rate limiting
+- ❌ Breaking changes without version increment
+
+## References
+
+- [REST API Design Best Practices](https://restfulapi.net/)
+- [HTTP Status Codes](https://httpstatuses.com/)
+- [API Versioning](https://www.freecodecamp.org/news/how-to-version-a-rest-api/)
+

package/augment-extensions/coding-standards/go/templates/prompts/cli.md

@@ -0,0 +1,225 @@
+# CLI Tool Project Template
+
+## Context
+
+You are generating Go code for a **CLI tool** project. This includes command-line applications, developer tools, and system utilities.
+
+## Standards
+
+Follow these Go coding standards for CLI tools:
+
+### Universal Rules
+
+1. **Naming Conventions**: Use MixedCaps for exported names, mixedCaps for unexported
+2. **Error Handling**: Return errors explicitly, provide helpful error messages
+3. **Testing**: Write table-driven tests, test command execution
+4. **Code Organization**: Keep packages flat and focused
+5. **Documentation**: Add godoc comments and usage examples
+6. **Performance**: Minimize startup time, lazy-load dependencies
+
+### CLI Tools Rules
+
+#### Command Parsing
+- Use Cobra library for command structure and parsing
+- Organize functionality into logical subcommands
+- Use typed flags (string, int, bool) with defaults
+- Validate arguments and flags before execution
+- Provide helpful usage examples in command help
+
+#### Configuration
+- Use Viper for configuration management
+- Support config files (YAML, JSON, TOML)
+- Support environment variables with consistent naming
+- Follow precedence: Flags > Env Vars > Config File > Defaults
+- Validate configuration on load
+
+#### Cross-Platform
+- Use `filepath` package for all path operations
+- Use standard exit codes (0 for success, 1-255 for errors)
+- Handle OS signals (SIGINT, SIGTERM) gracefully
+- Use `os.UserHomeDir()` for home directory
+- Test on Windows, macOS, and Linux
+
+## Key Requirements
+
+### Command Structure
+```go
+var rootCmd = &cobra.Command{
+    Use:   "myapp",
+    Short: "Brief description",
+    Long:  "Detailed description with examples",
+}
+
+var subCmd = &cobra.Command{
+    Use:   "sub [arg]",
+    Short: "Subcommand description",
+    Args:  cobra.ExactArgs(1),
+    RunE: func(cmd *cobra.Command, args []string) error {
+        return executeCommand(args[0])
+    },
+}
+
+func init() {
+    rootCmd.AddCommand(subCmd)
+}
+```
+
+### Flag Definition
+```go
+var (
+    outputFormat string
+    verbose      bool
+    maxResults   int
+)
+
+func init() {
+    cmd.Flags().StringVarP(&outputFormat, "output", "o", "table", "Output format")
+    cmd.Flags().BoolVarP(&verbose, "verbose", "v", false, "Verbose output")
+    cmd.Flags().IntVar(&maxResults, "limit", 10, "Maximum results")
+}
+```
+
+### Configuration Management
+```go
+func initConfig() {
+    viper.SetConfigName("config")
+    viper.AddConfigPath("$HOME/.myapp")
+    viper.AddConfigPath(".")
+    
+    viper.SetEnvPrefix("MYAPP")
+    viper.AutomaticEnv()
+    
+    viper.SetDefault("server.port", 8080)
+    
+    viper.ReadInConfig()
+}
+```
+
+### Cross-Platform Paths
+```go
+func getConfigPath() (string, error) {
+    home, err := os.UserHomeDir()
+    if err != nil {
+        return "", err
+    }
+    return filepath.Join(home, ".myapp", "config.yaml"), nil
+}
+```
+
+### Exit Codes
+```go
+const (
+    ExitSuccess      = 0
+    ExitError        = 1
+    ExitUsageError   = 2
+    ExitConfigError  = 3
+)
+
+func main() {
+    if err := rootCmd.Execute(); err != nil {
+        os.Exit(ExitError)
+    }
+}
+```
+
+### Signal Handling
+```go
+func runWithCancellation(ctx context.Context) error {
+    sigChan := make(chan os.Signal, 1)
+    signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)
+    
+    select {
+    case <-sigChan:
+        return fmt.Errorf("cancelled by user")
+    case <-ctx.Done():
+        return ctx.Err()
+    }
+}
+```
+
+## Common Patterns
+
+### Argument Validation
+```go
+var createCmd = &cobra.Command{
+    Args: cobra.ExactArgs(1),
+    PreRunE: func(cmd *cobra.Command, args []string) error {
+        if len(args[0]) < 3 {
+            return fmt.Errorf("name must be at least 3 characters")
+        }
+        return nil
+    },
+}
+```
+
+### Persistent Flags
+```go
+func init() {
+    // Available to all subcommands
+    rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file")
+    rootCmd.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "verbose")
+}
+```
+
+### Config File Generation
+```go
+var initConfigCmd = &cobra.Command{
+    Use:   "init-config",
+    Short: "Generate sample config",
+    RunE: func(cmd *cobra.Command, args []string) error {
+        viper.SetDefault("key", "value")
+        return viper.SafeWriteConfigAs("config.yaml")
+    },
+}
+```
+
+### Platform-Specific Code
+```go
+// Use build tags for platform-specific files
+//go:build unix
+package main
+
+// Or runtime checks
+func openBrowser(url string) error {
+    var cmd *exec.Cmd
+    switch runtime.GOOS {
+    case "darwin":
+        cmd = exec.Command("open", url)
+    case "windows":
+        cmd = exec.Command("cmd", "/c", "start", url)
+    default:
+        cmd = exec.Command("xdg-open", url)
+    }
+    return cmd.Start()
+}
+```
+
+## Tools
+
+Ensure generated code passes:
+- `go build` - Compiles without errors
+- `golangci-lint run` - Passes all linters
+- `go vet` - No suspicious constructs
+- `gofmt -d .` - Properly formatted
+- Test on multiple platforms (Windows, macOS, Linux)
+
+## Output Format
+
+Generate complete, production-ready Go code with:
+- Package declaration and imports
+- Root command and subcommands
+- Flag definitions with validation
+- Configuration management with Viper
+- Cross-platform path handling
+- Proper exit codes
+- Signal handling for graceful shutdown
+- Comprehensive help text and examples
+- Godoc comments
+
+## References
+
+- [Cobra Documentation](https://github.com/spf13/cobra)
+- [Viper Documentation](https://github.com/spf13/viper)
+- [CLI Best Practices](https://clig.dev/)
+- [Go filepath package](https://pkg.go.dev/path/filepath)
+