@ngxtm/devkit 3.4.0 → 3.4.1

package/rules/golang/cobra-cli/references/command-patterns.md

@@ -0,0 +1,224 @@
+# Cobra Command Patterns
+
+## Basic Structure
+
+```go
+package cmd
+
+import (
+    "fmt"
+    "os"
+    "github.com/spf13/cobra"
+)
+
+var rootCmd = &cobra.Command{
+    Use:   "myapp",
+    Short: "A brief description of your application",
+    Long: `A longer description that spans multiple lines
+and likely contains examples and usage of using your application.`,
+    Run: func(cmd *cobra.Command, args []string) {
+        // Root command logic (or show help)
+    },
+}
+
+func Execute() {
+    if err := rootCmd.Execute(); err != nil {
+        fmt.Fprintln(os.Stderr, err)
+        os.Exit(1)
+    }
+}
+
+func init() {
+    // Initialize flags and configuration
+    cobra.OnInitialize(initConfig)
+    
+    // Persistent flags (available to this command and all subcommands)
+    rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file")
+    rootCmd.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "verbose output")
+    
+    // Local flags (only for this command)
+    rootCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
+}
+```
+
+## Subcommands
+
+```go
+package cmd
+
+import (
+    "fmt"
+    "github.com/spf13/cobra"
+)
+
+var createCmd = &cobra.Command{
+    Use:   "create [name]",
+    Short: "Create a new resource",
+    Long:  `Create a new resource with the specified name.`,
+    Args:  cobra.ExactArgs(1), // Require exactly 1 argument
+    RunE: func(cmd *cobra.Command, args []string) error {
+        name := args[0]
+        
+        // Get flag values
+        dryRun, _ := cmd.Flags().GetBool("dry-run")
+        template, _ := cmd.Flags().GetString("template")
+        
+        if dryRun {
+            fmt.Printf("Would create: %s\n", name)
+            return nil
+        }
+        
+        return createResource(name, template)
+    },
+}
+
+func init() {
+    rootCmd.AddCommand(createCmd)
+    
+    createCmd.Flags().BoolP("dry-run", "n", false, "Dry run mode")
+    createCmd.Flags().StringP("template", "t", "default", "Template to use")
+    createCmd.MarkFlagRequired("template")
+}
+```
+
+## Argument Validation
+
+```go
+var cmd = &cobra.Command{
+    Use:   "process [file...]",
+    Short: "Process files",
+    // Argument validators
+    Args: cobra.MinimumNArgs(1),           // At least 1
+    // Args: cobra.MaximumNArgs(3),         // At most 3
+    // Args: cobra.ExactArgs(2),            // Exactly 2
+    // Args: cobra.RangeArgs(1, 3),         // 1 to 3
+    // Args: cobra.NoArgs,                  // None allowed
+    
+    // Custom validator
+    Args: func(cmd *cobra.Command, args []string) error {
+        for _, arg := range args {
+            if !isValidFile(arg) {
+                return fmt.Errorf("invalid file: %s", arg)
+            }
+        }
+        return nil
+    },
+    
+    RunE: func(cmd *cobra.Command, args []string) error {
+        for _, file := range args {
+            if err := processFile(file); err != nil {
+                return err
+            }
+        }
+        return nil
+    },
+}
+```
+
+## Flag Types
+
+```go
+var (
+    stringFlag   string
+    intFlag      int
+    boolFlag     bool
+    stringSlice  []string
+    stringToString map[string]string
+    durationFlag time.Duration
+)
+
+func init() {
+    // String
+    cmd.Flags().StringVarP(&stringFlag, "name", "n", "default", "Description")
+    
+    // Int
+    cmd.Flags().IntVarP(&intFlag, "count", "c", 10, "Number of items")
+    
+    // Bool
+    cmd.Flags().BoolVarP(&boolFlag, "verbose", "v", false, "Enable verbose")
+    
+    // String slice (can be specified multiple times)
+    cmd.Flags().StringSliceVarP(&stringSlice, "tag", "t", nil, "Tags")
+    
+    // String to string map
+    cmd.Flags().StringToStringVar(&stringToString, "label", nil, "Labels (key=value)")
+    
+    // Duration
+    cmd.Flags().DurationVar(&durationFlag, "timeout", 30*time.Second, "Timeout")
+}
+```
+
+## Hooks
+
+```go
+var cmd = &cobra.Command{
+    Use: "deploy",
+    
+    // Runs before Run
+    PreRunE: func(cmd *cobra.Command, args []string) error {
+        return validateConfig()
+    },
+    
+    // Main execution
+    RunE: func(cmd *cobra.Command, args []string) error {
+        return deploy()
+    },
+    
+    // Runs after Run (even if Run errors)
+    PostRunE: func(cmd *cobra.Command, args []string) error {
+        return cleanup()
+    },
+    
+    // Persistent versions run for all child commands too
+    PersistentPreRun: func(cmd *cobra.Command, args []string) {
+        initLogging()
+    },
+}
+```
+
+## Nested Commands
+
+```go
+// rootCmd → userCmd → createUserCmd
+var userCmd = &cobra.Command{
+    Use:   "user",
+    Short: "User management",
+}
+
+var createUserCmd = &cobra.Command{
+    Use:   "create [name]",
+    Short: "Create a user",
+    RunE: func(cmd *cobra.Command, args []string) error {
+        return createUser(args[0])
+    },
+}
+
+var listUserCmd = &cobra.Command{
+    Use:   "list",
+    Short: "List users",
+    RunE: func(cmd *cobra.Command, args []string) error {
+        return listUsers()
+    },
+}
+
+func init() {
+    rootCmd.AddCommand(userCmd)
+    userCmd.AddCommand(createUserCmd)
+    userCmd.AddCommand(listUserCmd)
+}
+```
+
+## Completions
+
+```go
+var cmd = &cobra.Command{
+    Use: "set-env [environment]",
+    ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+        return []string{"dev", "staging", "production"}, cobra.ShellCompDirectiveNoFileComp
+    },
+}
+
+// Generate completions
+// myapp completion bash > /etc/bash_completion.d/myapp
+// myapp completion zsh > "${fpath[1]}/_myapp"
+```

package/rules/golang/core/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: Go Core
+description: Go language fundamentals, concurrency, error handling, and project patterns.
+metadata:
+  labels: [golang, core, language]
+  triggers:
+    files: ['go.mod', '**/*.go']
+    keywords: [func, package, import, goroutine, chan]
+---
+
+# Go Core Standards
+
+## Goroutines & Channels
+
+```go
+// Spawn goroutine
+go func() {
+    result := process(data)
+    resultChan <- result
+}()
+
+// Unbuffered channel (synchronous)
+ch := make(chan int)
+
+// Buffered channel
+ch := make(chan int, 100)
+
+// Send and receive
+ch <- value      // Send
+value := <-ch    // Receive
+
+// Select for multiplexing
+select {
+case msg := <-msgChan:
+    handle(msg)
+case <-time.After(5 * time.Second):
+    return errors.New("timeout")
+case <-ctx.Done():
+    return ctx.Err()
+}
+```
+
+**Patterns**:
+- Worker pools with buffered channels
+- Fan-out/fan-in for parallel processing
+- Done channel for cancellation
+
+## Error Handling
+
+```go
+// Return errors, don't panic
+func fetchUser(id int) (*User, error) {
+    user, err := db.FindUser(id)
+    if err != nil {
+        return nil, fmt.Errorf("fetch user %d: %w", id, err)
+    }
+    return user, nil
+}
+
+// Error wrapping (Go 1.13+)
+if errors.Is(err, sql.ErrNoRows) {
+    return nil, ErrNotFound
+}
+
+// Type assertion for custom errors
+var apiErr *APIError
+if errors.As(err, &apiErr) {
+    log.Printf("API error: %d", apiErr.Code)
+}
+
+// Sentinel errors
+var ErrNotFound = errors.New("not found")
+```
+
+**Rules**:
+- Always check errors immediately
+- Wrap with context: `fmt.Errorf("operation: %w", err)`
+- Use `errors.Is` and `errors.As` for comparison
+- **Never**: `panic` for recoverable errors
+
+## Interfaces
+
+```go
+// Small interfaces
+type Reader interface {
+    Read(p []byte) (n int, err error)
+}
+
+type Writer interface {
+    Write(p []byte) (n int, err error)
+}
+
+// Composition
+type ReadWriter interface {
+    Reader
+    Writer
+}
+
+// Accept interfaces, return structs
+func ProcessData(r Reader) (*Result, error) {
+    data, err := io.ReadAll(r)
+    // ...
+    return &Result{}, nil
+}
+```
+
+**Best Practices**:
+- Define interfaces where used, not where implemented
+- Keep interfaces small (1-3 methods)
+- Use `interface{}` sparingly; prefer generics (Go 1.18+)
+
+## Context
+
+```go
+// Pass context as first parameter
+func fetchData(ctx context.Context, id int) (*Data, error) {
+    // Respect cancellation
+    select {
+    case <-ctx.Done():
+        return nil, ctx.Err()
+    default:
+    }
+
+    // Use context with HTTP requests
+    req, _ := http.NewRequestWithContext(ctx, "GET", url, nil)
+    return client.Do(req)
+}
+
+// Add timeout
+ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+defer cancel()
+
+// Add values (use sparingly)
+ctx = context.WithValue(ctx, requestIDKey, reqID)
+```
+
+**Rules**:
+- Never store context in structs
+- Always call cancel function (use defer)
+- Use for cancellation, deadlines, request-scoped values only
+
+## Project Structure
+
+```
+project/
+├── cmd/
+│   └── myapp/
+│       └── main.go       # Entry point
+├── internal/             # Private packages
+│   ├── handler/
+│   ├── service/
+│   └── repository/
+├── pkg/                  # Public packages
+├── api/                  # API definitions (proto, OpenAPI)
+├── configs/
+├── go.mod
+└── go.sum
+```
+
+**Conventions**:
+- `internal/` prevents external imports
+- `cmd/` for multiple entry points
+- Flat structure for small projects
+
+## Testing
+
+```go
+// Table-driven tests
+func TestAdd(t *testing.T) {
+    tests := []struct {
+        name     string
+        a, b     int
+        expected int
+    }{
+        {"positive", 1, 2, 3},
+        {"negative", -1, -1, -2},
+        {"zero", 0, 0, 0},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            result := Add(tt.a, tt.b)
+            if result != tt.expected {
+                t.Errorf("Add(%d, %d) = %d; want %d", tt.a, tt.b, result, tt.expected)
+            }
+        })
+    }
+}
+
+// Parallel tests
+func TestParallel(t *testing.T) {
+    t.Parallel()
+    // ...
+}
+
+// Benchmarks
+func BenchmarkProcess(b *testing.B) {
+    for i := 0; i < b.N; i++ {
+        Process(data)
+    }
+}
+```
+
+## Performance
+
+1. **Preallocate slices**: `make([]T, 0, expectedLen)`
+2. **Avoid allocations**: Reuse buffers, use `sync.Pool`
+3. **Profile first**: `go tool pprof` before optimizing
+4. **Escape analysis**: `go build -gcflags='-m'` to check heap escapes
+5. **String building**: Use `strings.Builder` not `+` concatenation

package/rules/golang/core/references/REFERENCE.md

@@ -0,0 +1,14 @@
+# Go Core References
+
+## References
+
+- [**Error Handling**](error-handling.md) - Error wrapping, custom errors, sentinel errors
+- [**Concurrency Patterns**](concurrency-patterns.md) - Goroutines, channels, sync primitives
+
+## Quick Checks
+
+- [ ] Always handle errors explicitly
+- [ ] Use `fmt.Errorf` with `%w` for wrapping
+- [ ] Context for cancellation and timeouts
+- [ ] Prefer channels for communication, mutexes for state
+- [ ] Use `defer` for cleanup

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