@ngxtm/devkit 3.3.0 → 3.4.1

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

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