ga-plugins-cli 0.1.0 → 0.1.1

package/plugins/go-standards/skills/concurrency.md

@@ -0,0 +1,336 @@
+# Concurrency Standard
+
+Go's concurrency primitives are powerful and easy to misuse. These rules
+prevent goroutine leaks, data races, and deadlocks — the three most common
+concurrency bugs in migrated Java services.
+
+---
+
+## Rule 1 — Always pass `context.Context` as the first argument
+
+Every function that does I/O, blocks, or can be cancelled must accept
+`context.Context` as its first parameter. Never store a context in a struct.
+
+### DO
+
+```go
+// Every layer propagates the context
+func (uc *UserUsecase) Create(ctx context.Context, input CreateUserInput) (*User, error) {
+    return uc.repo.Create(ctx, &User{Email: input.Email})
+}
+
+func (r *userRepository) Create(ctx context.Context, u *User) (*User, error) {
+    _, err := r.db.ExecContext(ctx, insertUser, u.Email, u.Name)
+    if err != nil {
+        return nil, fmt.Errorf("insert user: %w", err)
+    }
+    return u, nil
+}
+```
+
+### DO NOT
+
+```go
+// WRONG: context stored in struct
+type UserUsecase struct {
+    ctx context.Context  // WRONG: contexts belong to calls, not structs
+    repo UserRepository
+}
+
+// WRONG: context.Background() created inside a function — ignores cancellation
+func (r *userRepository) Create(u *User) (*User, error) {
+    // WRONG: creates a new root context, ignoring the caller's deadline/cancellation
+    _, err := r.db.ExecContext(context.Background(), insertUser, u.Email)
+    return u, err
+}
+
+// WRONG: context not threaded through — downstream cannot be cancelled
+func (uc *UserUsecase) BulkCreate(users []User) error {
+    for _, u := range users {
+        uc.repo.Create(&u)  // WRONG: no context
+    }
+    return nil
+}
+```
+
+---
+
+## Rule 2 — Cancel contexts; always `defer cancel()`
+
+Every call to `context.WithCancel`, `context.WithTimeout`, or
+`context.WithDeadline` returns a cancel function. Always call it, always
+with defer, to release resources.
+
+### DO
+
+```go
+func (uc *UserUsecase) FetchExternal(ctx context.Context, id string) (*User, error) {
+    // Enforce a maximum wait time for the external call
+    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+    defer cancel()  // releases timer resources whether we return early or not
+
+    return uc.externalClient.Get(ctx, id)
+}
+```
+
+```go
+// In main — cancel on shutdown
+ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+defer stop()  // always called, even if we panic-recover
+```
+
+### DO NOT
+
+```go
+// WRONG: cancel never called — goroutine/timer leak
+func (uc *UserUsecase) FetchExternal(ctx context.Context, id string) (*User, error) {
+    ctx, _ = context.WithTimeout(ctx, 5*time.Second)  // WRONG: _ discards cancel
+    return uc.externalClient.Get(ctx, id)
+}
+
+// WRONG: cancel called only in the happy path
+func process(ctx context.Context) error {
+    ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
+    result, err := doWork(ctx)
+    if err != nil {
+        return err  // WRONG: cancel not called on error path
+    }
+    cancel()
+    return use(result)
+}
+```
+
+---
+
+## Rule 3 — Goroutines must always have a termination path
+
+Every goroutine you launch must have a clear way to stop: either a
+`context.Context` that will be cancelled, a done channel, or a fixed
+lifetime (e.g., handles one request then exits). Goroutines that run
+forever without a stop signal are leaks.
+
+### DO
+
+```go
+// Background worker with context-based cancellation
+func (w *Worker) Start(ctx context.Context) {
+    go func() {
+        ticker := time.NewTicker(30 * time.Second)
+        defer ticker.Stop()
+
+        for {
+            select {
+            case <-ctx.Done():
+                return  // clean exit when context is cancelled
+            case <-ticker.C:
+                if err := w.runJob(ctx); err != nil {
+                    w.logger.Error("job failed", zap.Error(err))
+                }
+            }
+        }
+    }()
+}
+```
+
+```go
+// Fire-and-forget with timeout — not truly fire-and-forget, has bounded lifetime
+func sendNotificationAsync(ctx context.Context, userID string, client NotificationClient, logger *zap.Logger) {
+    go func() {
+        ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
+        defer cancel()
+
+        if err := client.Notify(ctx, userID); err != nil {
+            logger.Error("async notification failed",
+                zap.Error(err),
+                zap.String("user_id", userID),
+            )
+        }
+    }()
+}
+```
+
+### DO NOT
+
+```go
+// WRONG: goroutine with no termination path
+go func() {
+    for {
+        processQueue()  // WRONG: runs forever, cannot be stopped for graceful shutdown
+        time.Sleep(time.Second)
+    }
+}()
+
+// WRONG: goroutine inherits a context that will be cancelled before it finishes
+func (h *UserHandler) Create(w http.ResponseWriter, r *http.Request) {
+    user, _ := h.uc.Create(r.Context(), input)
+    go func() {
+        // WRONG: r.Context() is cancelled when the HTTP response is sent
+        // This goroutine will see context cancellation immediately after the handler returns
+        h.auditLogger.Log(r.Context(), user)
+    }()
+}
+// Fix: pass context.WithoutCancel(r.Context()) or a new background context
+```
+
+---
+
+## Rule 4 — `sync.WaitGroup` for fan-out patterns
+
+When launching multiple goroutines that must all complete before proceeding,
+use `sync.WaitGroup`. Always call `wg.Add(n)` before launching goroutines,
+never inside them.
+
+### DO
+
+```go
+func (uc *UserUsecase) BulkEnrich(ctx context.Context, users []*User) error {
+    var wg sync.WaitGroup
+    errs := make(chan error, len(users))  // buffered so sends never block
+
+    for _, u := range users {
+        wg.Add(1)
+        go func(user *User) {
+            defer wg.Done()
+            if err := uc.enrich(ctx, user); err != nil {
+                errs <- fmt.Errorf("enrich user %s: %w", user.ID, err)
+            }
+        }(u)
+    }
+
+    wg.Wait()
+    close(errs)
+
+    // Collect first error (or use errgroup for cleaner multi-error handling)
+    for err := range errs {
+        if err != nil {
+            return err
+        }
+    }
+    return nil
+}
+```
+
+### DO NOT
+
+```go
+// WRONG: wg.Add inside goroutine — race condition
+for _, u := range users {
+    go func(user *User) {
+        wg.Add(1)   // WRONG: may race with wg.Wait()
+        defer wg.Done()
+        enrich(ctx, user)
+    }(u)
+}
+wg.Wait()
+```
+
+---
+
+## Rule 5 — `errgroup` for concurrent tasks with error collection
+
+Prefer `golang.org/x/sync/errgroup` over manual WaitGroup + error channel
+for fan-out where you care about errors.
+
+```go
+import "golang.org/x/sync/errgroup"
+
+func (uc *UserUsecase) CreateWithAudit(ctx context.Context, input CreateUserInput) (*User, error) {
+    g, ctx := errgroup.WithContext(ctx)
+
+    var user *User
+    g.Go(func() error {
+        var err error
+        user, err = uc.repo.Create(ctx, &User{Email: input.Email})
+        return err
+    })
+
+    g.Go(func() error {
+        return uc.auditLog.Record(ctx, "user.create", input.Email)
+    })
+
+    if err := g.Wait(); err != nil {
+        return nil, fmt.Errorf("create with audit: %w", err)
+    }
+    return user, nil
+}
+```
+
+---
+
+## Rule 6 — Protecting shared state
+
+Prefer communicating over sharing. When shared state is necessary, protect
+it with `sync.Mutex`. Use `sync.RWMutex` when reads are far more frequent
+than writes.
+
+```go
+// Cache with RWMutex — many concurrent readers, occasional writer
+type UserCache struct {
+    mu    sync.RWMutex
+    store map[string]*domain.User
+}
+
+func (c *UserCache) Get(id string) (*domain.User, bool) {
+    c.mu.RLock()
+    defer c.mu.RUnlock()
+    u, ok := c.store[id]
+    return u, ok
+}
+
+func (c *UserCache) Set(id string, u *domain.User) {
+    c.mu.Lock()
+    defer c.mu.Unlock()
+    c.store[id] = u
+}
+```
+
+### DO NOT
+
+```go
+// WRONG: unprotected map access from multiple goroutines — data race
+type BadCache struct {
+    store map[string]*User  // WRONG: no mutex
+}
+
+func (c *BadCache) Get(id string) *User { return c.store[id] }  // WRONG
+func (c *BadCache) Set(id string, u *User) { c.store[id] = u }  // WRONG
+
+// WRONG: holding lock across I/O
+func (c *UserCache) Fetch(ctx context.Context, id string) (*User, error) {
+    c.mu.Lock()
+    defer c.mu.Unlock()
+    // WRONG: lock held while doing a network call — blocks all other readers
+    return c.client.Get(ctx, id)
+}
+```
+
+---
+
+## Rule 7 — Never pass a loop variable to a goroutine by closure in Go < 1.22
+
+In Go 1.22+ the loop variable is per-iteration and this is safe. For Go
+1.21 and earlier, always capture loop variables explicitly.
+
+```go
+// Safe in Go 1.22+ (this project uses Go 1.23 — but be explicit for clarity)
+for _, u := range users {
+    u := u  // explicit capture — safe in all versions, documents intent
+    go func() {
+        process(u)
+    }()
+}
+```
+
+---
+
+## Quick Reference: Java → Go Concurrency Mapping
+
+| Java | Go |
+|------|----|
+| `ExecutorService` / `ThreadPoolExecutor` | `errgroup` or goroutines + WaitGroup |
+| `CompletableFuture` | goroutine + channel or `errgroup` |
+| `synchronized` method | `sync.Mutex` wrapping the method body |
+| `ConcurrentHashMap` | `sync.Map` or `map` + `sync.RWMutex` |
+| `Thread.sleep()` in tests | channel receive with timeout or `time.After` |
+| `InterruptedException` | `ctx.Done()` / `context.Canceled` |
+| `@Async` Spring annotation | `go func() { ... }()` with context propagation |

package/plugins/go-standards/skills/config.md

@@ -0,0 +1,267 @@
+# Config Management Standard
+
+All configuration comes from environment variables. This is the 12-factor
+app method and is mandatory for every service in this fleet.
+
+---
+
+## Rule 1 — Environment variables only; no config files at runtime
+
+No YAML, TOML, or JSON config files read at runtime. No `application.properties`.
+Environment variables are injected by the container orchestrator (Kubernetes
+ConfigMaps and Secrets) and are the single source of truth at runtime.
+
+### Java equivalent
+Spring Boot's `application.properties` / `@Value` / `@ConfigurationProperties`
+→ Go struct with env tags, loaded once in `main`.
+
+---
+
+## Config Struct with env Tags
+
+Use `github.com/caarlos0/env/v11` (or the team-agreed env loader). Define
+one `Config` struct per service. Tag every field.
+
+```go
+// config/config.go
+package config
+
+import (
+    "fmt"
+
+    "github.com/caarlos0/env/v11"
+)
+
+// Config holds all configuration for this service.
+// Fields tagged `required` cause Load() to return an error if absent.
+// Fields with `envDefault` use that value when the variable is unset.
+type Config struct {
+    // Server
+    Port            string `env:"PORT"              envDefault:"8080"`
+    ShutdownTimeout int    `env:"SHUTDOWN_TIMEOUT"  envDefault:"10"` // seconds
+
+    // Database
+    DBHost     string `env:"DB_HOST"     required:"true"`
+    DBPort     string `env:"DB_PORT"     envDefault:"5432"`
+    DBName     string `env:"DB_NAME"     required:"true"`
+    DBUser     string `env:"DB_USER"     required:"true"`
+    DBPassword string `env:"DB_PASSWORD" required:"true"`
+    DBSSLMode  string `env:"DB_SSLMODE"  envDefault:"require"`
+
+    // Observability
+    LogLevel       string `env:"LOG_LEVEL"        envDefault:"info"`
+    OTELEndpoint   string `env:"OTEL_ENDPOINT"    envDefault:"http://otel-collector:4318"`
+    ServiceName    string `env:"SERVICE_NAME"     required:"true"`
+    ServiceVersion string `env:"SERVICE_VERSION"  envDefault:"dev"`
+
+    // Auth
+    JWTSecret string `env:"JWT_SECRET" required:"true"`
+
+    // External services (example)
+    NotificationServiceURL string `env:"NOTIFICATION_SERVICE_URL" required:"true"`
+}
+
+// Load parses environment variables into Config.
+// Returns an error if any required variable is missing or has an invalid type.
+func Load() (*Config, error) {
+    cfg := &Config{}
+    if err := env.Parse(cfg); err != nil {
+        return nil, fmt.Errorf("loading config: %w", err)
+    }
+    return cfg, nil
+}
+
+// DSN builds the postgres connection string from individual fields.
+// Never expose this method's output in logs.
+func (c *Config) DSN() string {
+    return fmt.Sprintf(
+        "host=%s port=%s dbname=%s user=%s password=%s sslmode=%s",
+        c.DBHost, c.DBPort, c.DBName, c.DBUser, c.DBPassword, c.DBSSLMode,
+    )
+}
+```
+
+---
+
+## Rule 2 — Load once at startup; pass as struct
+
+Call `config.Load()` exactly once in `main.go`. Pass the populated struct
+(or specific fields) to constructors. Never call `os.Getenv` anywhere else
+in the codebase.
+
+### DO
+
+```go
+// cmd/server/main.go
+cfg, err := config.Load()
+if err != nil {
+    log.Fatalf("loading config: %v", err)
+}
+
+// Pass the config struct — or specific fields — to each constructor
+db, err := repository.OpenDB(cfg.DSN())
+if err != nil {
+    log.Fatalf("opening db: %v", err)
+}
+
+notifClient := notification.NewClient(cfg.NotificationServiceURL)
+```
+
+### DO NOT
+
+```go
+// WRONG: reading env vars scattered across the codebase
+func NewUserRepository(db *sql.DB) *UserRepository {
+    timeout, _ := strconv.Atoi(os.Getenv("DB_TIMEOUT"))  // WRONG
+    return &UserRepository{db: db, timeout: timeout}
+}
+
+// WRONG: global config variable
+var GlobalConfig *config.Config  // WRONG: hidden dependency, untestable
+
+// WRONG: reading config in a handler
+func (h *UserHandler) Create(w http.ResponseWriter, r *http.Request) {
+    maxUsers, _ := strconv.Atoi(os.Getenv("MAX_USERS"))  // WRONG
+    ...
+}
+```
+
+---
+
+## Rule 3 — Secrets: never commit, never log
+
+Secrets are values in `DBPassword`, `JWTSecret`, API keys, etc.
+
+Rules:
+1. Never commit real secret values to git — `.env` is in `.gitignore`
+2. Never log a secret or a struct that contains one
+3. Never include secrets in error messages returned to clients
+4. Implement `fmt.Stringer` with redaction if the Config struct is ever logged
+
+```go
+// config/config.go — safe String() prevents accidental logging of secrets
+func (c *Config) String() string {
+    return fmt.Sprintf(
+        "Config{Port:%s, DBHost:%s, DBName:%s, LogLevel:%s, ServiceName:%s}",
+        c.Port, c.DBHost, c.DBName, c.LogLevel, c.ServiceName,
+        // NOTE: DBPassword, JWTSecret intentionally omitted
+    )
+}
+```
+
+```go
+// DO: log the safe representation
+logger.Info("service starting", zap.String("config", cfg.String()))
+
+// DO NOT: log the raw struct
+logger.Info("service starting", zap.Any("config", cfg))  // WRONG: leaks secrets
+```
+
+---
+
+## `.env.example` — Documents all variables
+
+Every service ships a `.env.example` that documents every variable with a
+description but uses only placeholder values. This is committed to git and
+is the primary operator documentation for deployment.
+
+```bash
+# .env.example
+# Copy to .env for local development. Never commit .env.
+
+# --- Server ---
+PORT=8080
+SHUTDOWN_TIMEOUT=10   # seconds to wait for in-flight requests on SIGTERM
+
+# --- Database ---
+DB_HOST=localhost     # required — PostgreSQL host
+DB_PORT=5432
+DB_NAME=myservice_db  # required
+DB_USER=myservice     # required
+DB_PASSWORD=CHANGEME  # required — use a strong random value in production
+DB_SSLMODE=disable    # use 'require' in production
+
+# --- Observability ---
+LOG_LEVEL=info        # debug | info | warn | error
+OTEL_ENDPOINT=http://otel-collector:4318
+SERVICE_NAME=my-service    # required — used as Prometheus/Loki label
+SERVICE_VERSION=dev
+
+# --- Auth ---
+JWT_SECRET=CHANGEME   # required — minimum 32 bytes of entropy in production
+
+# --- External services ---
+NOTIFICATION_SERVICE_URL=http://notification-svc:8080  # required
+```
+
+`.gitignore` entry (must be present):
+
+```
+.env
+*.env.local
+```
+
+---
+
+## Rule 4 — Type-safe default handling
+
+Numeric and boolean env vars must be declared with the correct Go type in
+the Config struct so the env loader validates them automatically.
+
+```go
+type Config struct {
+    Port            int           `env:"PORT"             envDefault:"8080"`
+    ShutdownTimeout time.Duration `env:"SHUTDOWN_TIMEOUT" envDefault:"10s"`
+    EnableProfiling bool          `env:"ENABLE_PROFILING" envDefault:"false"`
+    MaxDBConns      int           `env:"MAX_DB_CONNS"     envDefault:"25"`
+}
+```
+
+### DO NOT
+
+```go
+// WRONG: everything as string, manual conversion at use site
+type Config struct {
+    Port string `env:"PORT"`  // WRONG: forces strconv everywhere
+}
+
+port, _ := strconv.Atoi(cfg.Port)  // WRONG: error ignored, repeated across codebase
+```
+
+---
+
+## Validation Beyond Required Tags
+
+For cross-field validation or range checks, validate in `Load()` after
+parsing:
+
+```go
+func Load() (*Config, error) {
+    cfg := &Config{}
+    if err := env.Parse(cfg); err != nil {
+        return nil, fmt.Errorf("loading config: %w", err)
+    }
+
+    if cfg.MaxDBConns < 1 || cfg.MaxDBConns > 100 {
+        return nil, fmt.Errorf("MAX_DB_CONNS must be between 1 and 100, got %d", cfg.MaxDBConns)
+    }
+    if len(cfg.JWTSecret) < 32 {
+        return nil, fmt.Errorf("JWT_SECRET must be at least 32 characters")
+    }
+
+    return cfg, nil
+}
+```
+
+---
+
+## Quick Reference: Java → Go Config Mapping
+
+| Spring Boot | Go |
+|-------------|----|
+| `application.properties` | environment variables |
+| `@Value("${server.port}")` | `env:"PORT"` tag on struct field |
+| `@ConfigurationProperties(prefix="db")` | nested struct or flat `Config` struct |
+| `spring.datasource.url` | `DB_HOST`, `DB_PORT`, `DB_NAME` separate vars |
+| Vault / AWS Secrets Manager | Env vars injected by K8s Secrets (same end result) |
+| Profile-based config (`dev`, `prod`) | Env vars differ per deployment; no profile concept |