ga-plugins-cli 0.1.0 → 0.1.2

package/plugins/go-standards/skills/error-handling.md

@@ -0,0 +1,286 @@
+# Error Handling Standard
+
+Go does not have exceptions. Errors are values — treat them accordingly.
+Every pattern below has a direct Java equivalent called out so the migration
+path is clear.
+
+---
+
+## Rule 1 — Return errors; never panic in business code
+
+`panic` is reserved for truly unrecoverable situations at program startup
+(e.g., a required config value is missing, a dependency cannot be
+initialized). Business logic, handlers, usecases, and repositories must
+return errors.
+
+### Java equivalent
+- Java `throw new RuntimeException(...)` → Go `return nil, err`
+- Java `throw new IllegalArgumentException(...)` → Go `return nil, domain.ErrInvalidInput`
+
+### DO
+
+```go
+// internal/usecase/user_usecase.go
+func (uc *UserUsecase) Create(ctx context.Context, input CreateUserInput) (*domain.User, error) {
+    if input.Email == "" {
+        return nil, fmt.Errorf("create user: %w", domain.ErrInvalidInput)
+    }
+    u, err := uc.repo.Create(ctx, &domain.User{Email: input.Email})
+    if err != nil {
+        return nil, fmt.Errorf("create user: %w", err)
+    }
+    return u, nil
+}
+```
+
+### DO NOT
+
+```go
+// WRONG: panic in business code
+func (uc *UserUsecase) Create(ctx context.Context, input CreateUserInput) *domain.User {
+    if input.Email == "" {
+        panic("email is required")  // WRONG — callers cannot recover from this cleanly
+    }
+    u, err := uc.repo.Create(ctx, &domain.User{Email: input.Email})
+    if err != nil {
+        panic(err)  // WRONG
+    }
+    return u
+}
+```
+
+---
+
+## Rule 2 — Wrap errors with context using `%w`
+
+Every error that propagates upward must carry enough context to understand
+what operation failed without reading stack traces. Use `fmt.Errorf` with
+the `%w` verb to wrap, preserving the original error for `errors.Is` /
+`errors.As` inspection.
+
+Convention for the message: `"<verb> <noun>: <original>"` — lowercase, no
+trailing period.
+
+### DO
+
+```go
+func (r *userRepository) FindByID(ctx context.Context, id string) (*domain.User, error) {
+    var u domain.User
+    if err := r.db.QueryRowContext(ctx, queryFindByID, id).Scan(&u.ID, &u.Email, &u.Name); err != nil {
+        if errors.Is(err, sql.ErrNoRows) {
+            return nil, fmt.Errorf("find user by id %s: %w", id, domain.ErrNotFound)
+        }
+        return nil, fmt.Errorf("find user by id %s: %w", id, err)
+    }
+    return &u, nil
+}
+
+func (uc *UserUsecase) Get(ctx context.Context, id string) (*domain.User, error) {
+    u, err := uc.repo.FindByID(ctx, id)
+    if err != nil {
+        return nil, fmt.Errorf("get user: %w", err)  // adds layer, preserves sentinel
+    }
+    return u, nil
+}
+```
+
+A log at the top will show the full chain:
+```
+get user: find user by id abc123: not found
+```
+
+### DO NOT
+
+```go
+// WRONG: swallow context
+func (r *userRepository) FindByID(ctx context.Context, id string) (*domain.User, error) {
+    var u domain.User
+    err := r.db.QueryRowContext(ctx, queryFindByID, id).Scan(&u.ID, &u.Email)
+    if err != nil {
+        return nil, errors.New("database error")  // WRONG: caller cannot inspect original
+    }
+    return &u, nil
+}
+
+// WRONG: use %v instead of %w (loses inspectability)
+return nil, fmt.Errorf("find user: %v", err)  // WRONG: errors.Is() won't work
+```
+
+---
+
+## Rule 3 — Sentinel errors for expected domain cases
+
+Define sentinel errors in `internal/domain/errors.go`. Use them to signal
+known, expected conditions that callers must handle differently from
+unexpected infrastructure failures.
+
+### DO
+
+```go
+// internal/domain/errors.go
+package domain
+
+import "errors"
+
+var (
+    ErrNotFound      = errors.New("not found")
+    ErrAlreadyExists = errors.New("already exists")
+    ErrInvalidInput  = errors.New("invalid input")
+    ErrUnauthorized  = errors.New("unauthorized")
+    ErrForbidden     = errors.New("forbidden")
+)
+```
+
+```go
+// Caller inspects with errors.Is — works through wrapping chains
+user, err := uc.Get(ctx, id)
+if errors.Is(err, domain.ErrNotFound) {
+    respondError(w, http.StatusNotFound, "user not found", "NOT_FOUND")
+    return
+}
+if err != nil {
+    respondError(w, http.StatusInternalServerError, "internal error", "INTERNAL")
+    return
+}
+```
+
+### DO NOT
+
+```go
+// WRONG: string comparison to detect error types
+if err.Error() == "not found" {  // WRONG: fragile, breaks on wrap
+    ...
+}
+
+// WRONG: bespoke error struct per usecase without sentinel
+type UserNotFoundError struct{ ID string }
+func (e UserNotFoundError) Error() string { return "user " + e.ID + " not found" }
+// Creates an explosion of error types — use sentinels + wrapped context instead
+```
+
+---
+
+## Rule 4 — Error type hierarchy
+
+```
+domain/errors.go        — sentinel errors (ErrNotFound, ErrInvalidInput, ...)
+repository layer        — wraps stdlib/driver errors into domain sentinels
+usecase layer           — wraps domain errors with operation context
+handler layer           — maps domain sentinels to HTTP status codes
+```
+
+Infrastructure errors (DB connectivity, timeout) surface as non-sentinel
+errors and map to 500. Domain errors (not found, invalid) map to 4xx.
+
+```go
+// internal/handler/respond.go
+func respondError(w http.ResponseWriter, err error) {
+    switch {
+    case errors.Is(err, domain.ErrNotFound):
+        writeErrorBody(w, http.StatusNotFound, err.Error(), "NOT_FOUND")
+    case errors.Is(err, domain.ErrAlreadyExists):
+        writeErrorBody(w, http.StatusConflict, err.Error(), "CONFLICT")
+    case errors.Is(err, domain.ErrInvalidInput):
+        writeErrorBody(w, http.StatusBadRequest, err.Error(), "BAD_REQUEST")
+    case errors.Is(err, domain.ErrUnauthorized):
+        writeErrorBody(w, http.StatusUnauthorized, err.Error(), "UNAUTHORIZED")
+    case errors.Is(err, domain.ErrForbidden):
+        writeErrorBody(w, http.StatusForbidden, err.Error(), "FORBIDDEN")
+    default:
+        writeErrorBody(w, http.StatusInternalServerError, "internal server error", "INTERNAL")
+    }
+}
+```
+
+---
+
+## Rule 5 — Never log AND return an error
+
+The function that logs an error is the one that handles it (i.e., stops
+propagation). If you return an error to the caller you trust the caller to
+log or handle it. Doing both results in duplicate log entries and confusion
+about where the error originates.
+
+### Java equivalent
+Java's common pattern of `logger.error("...", e); throw e;` is a bug in Go.
+
+### DO
+
+```go
+// repository: wraps and returns — does NOT log
+func (r *userRepository) FindByID(ctx context.Context, id string) (*domain.User, error) {
+    // ... query ...
+    if err != nil {
+        return nil, fmt.Errorf("find user by id: %w", err)  // return only
+    }
+    return &u, nil
+}
+
+// handler: the final handler logs once and responds
+func (h *UserHandler) Get(w http.ResponseWriter, r *http.Request) {
+    user, err := h.uc.Get(r.Context(), chi.URLParam(r, "id"))
+    if err != nil {
+        h.logger.Error("get user", zap.Error(err))  // log once here
+        respondError(w, err)
+        return
+    }
+    respondJSON(w, http.StatusOK, user)
+}
+```
+
+### DO NOT
+
+```go
+// WRONG: log AND return at every layer
+func (r *userRepository) FindByID(ctx context.Context, id string) (*domain.User, error) {
+    // ... query ...
+    if err != nil {
+        r.logger.Error("db error", zap.Error(err))  // WRONG: log here...
+        return nil, fmt.Errorf("find user: %w", err)
+    }
+    return &u, nil
+}
+
+func (uc *UserUsecase) Get(ctx context.Context, id string) (*domain.User, error) {
+    u, err := uc.repo.FindByID(ctx, id)
+    if err != nil {
+        uc.logger.Error("usecase error", zap.Error(err))  // WRONG: ...and again here
+        return nil, fmt.Errorf("get user: %w", err)
+    }
+    return u, nil
+}
+// Result: same error logged 3 times at different layers
+```
+
+---
+
+## Rule 6 — panic is acceptable only during init
+
+```go
+// cmd/server/main.go — panic at startup is acceptable
+cfg, err := config.Load()
+if err != nil {
+    log.Fatalf("loading config: %v", err)  // os.Exit(1) via log.Fatal — ok at startup
+}
+
+db, err := sql.Open("postgres", cfg.DSN)
+if err != nil {
+    log.Fatalf("opening db: %v", err)
+}
+```
+
+Using `log.Fatalf` (which calls `os.Exit(1)`) at startup is fine. Using
+`panic` inside a request handler, usecase, or repository is never acceptable.
+
+---
+
+## Quick Reference: Java → Go Error Mapping
+
+| Java | Go |
+|------|----|
+| `throw new NotFoundException(id)` | `return nil, fmt.Errorf("find %s: %w", id, domain.ErrNotFound)` |
+| `throw new IllegalArgumentException("...")` | `return nil, fmt.Errorf("validate input: %w", domain.ErrInvalidInput)` |
+| `catch (Exception e) { throw new RuntimeException(e); }` | `return nil, fmt.Errorf("operation: %w", err)` |
+| `try { ... } catch (Exception e) { logger.error(...); }` | `if err != nil { logger.Error(...); }` — do not re-throw |
+| `Optional<User>.orElseThrow(...)` | `if u == nil { return nil, domain.ErrNotFound }` |
+| Checked exception in signature | error return value (compiler enforces handling) |

package/plugins/go-standards/skills/http-chi.md

@@ -0,0 +1,390 @@
+# HTTP / chi Standard
+
+All HTTP services use github.com/go-chi/chi/v5 as the router. This skill
+defines canonical patterns for router setup, handler signature, request
+decoding, response helpers, middleware, and health endpoints.
+
+---
+
+## Router Setup
+
+Always create the router in `cmd/server/main.go`. Apply global middleware in
+this fixed order so request IDs and trace context are available to all
+subsequent middleware.
+
+```go
+import (
+    "github.com/go-chi/chi/v5"
+    "github.com/go-chi/chi/v5/middleware"
+    "github.com/go-chi/cors"
+)
+
+r := chi.NewRouter()
+
+// Order matters — RequestID must be first so all downstream middleware can read it
+r.Use(middleware.RequestID)
+r.Use(middleware.RealIP)
+r.Use(middleware.Logger)       // chi's built-in access log (swap for zap middleware in prod)
+r.Use(middleware.Recoverer)    // catches panics, returns 500
+r.Use(middleware.Compress(5))
+
+r.Use(cors.Handler(cors.Options{
+    AllowedOrigins:   []string{"https://*.yourdomain.com"},
+    AllowedMethods:   []string{"GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"},
+    AllowedHeaders:   []string{"Accept", "Authorization", "Content-Type", "X-Request-ID"},
+    ExposedHeaders:   []string{"X-Request-ID"},
+    AllowCredentials: true,
+    MaxAge:           300,
+}))
+
+r.Route("/api/v1", func(r chi.Router) {
+    r.Mount("/users",  userHandler.Routes())
+    r.Mount("/orders", orderHandler.Routes())
+})
+
+r.Get("/health", healthHandler.Health)
+r.Get("/ready",  healthHandler.Ready)
+r.Handle("/metrics", promhttp.Handler())
+```
+
+---
+
+## Handler Type and Constructor
+
+Each resource gets its own handler struct. The struct holds only the usecase
+interface and logger — never a concrete repository, never a DB connection.
+
+```go
+// internal/handler/user_handler.go
+package handler
+
+import (
+    "net/http"
+
+    "github.com/go-chi/chi/v5"
+    "go.uber.org/zap"
+
+    "github.com/zokypesch/go-ga-lib/internal/domain"
+)
+
+type UserHandler struct {
+    uc     domain.UserUsecase
+    logger *zap.Logger
+}
+
+func NewUserHandler(uc domain.UserUsecase, logger *zap.Logger) *UserHandler {
+    return &UserHandler{uc: uc, logger: logger}
+}
+
+// Routes registers all user routes on a chi sub-router.
+func (h *UserHandler) Routes() chi.Router {
+    r := chi.NewRouter()
+    r.Get("/",        h.List)
+    r.Post("/",       h.Create)
+    r.Get("/{id}",    h.Get)
+    r.Put("/{id}",    h.Update)
+    r.Delete("/{id}", h.Delete)
+    return r
+}
+```
+
+---
+
+## Handler Signature
+
+Every handler has the standard `http.HandlerFunc` signature. Handlers are
+thin: decode request → call usecase → encode response. No business logic here.
+
+```go
+func (h *UserHandler) Create(w http.ResponseWriter, r *http.Request) {
+    var input domain.CreateUserInput
+    if err := decodeJSON(r, &input); err != nil {
+        respondError(w, http.StatusBadRequest, err.Error(), "BAD_REQUEST")
+        return
+    }
+
+    user, err := h.uc.Create(r.Context(), input)
+    if err != nil {
+        h.logger.Error("create user", zap.Error(err), zap.String("request_id", middleware.GetReqID(r.Context())))
+        respondError(w, err)
+        return
+    }
+
+    respondJSON(w, http.StatusCreated, user)
+}
+
+func (h *UserHandler) Get(w http.ResponseWriter, r *http.Request) {
+    id := chi.URLParam(r, "id")
+
+    user, err := h.uc.Get(r.Context(), id)
+    if err != nil {
+        h.logger.Error("get user", zap.Error(err), zap.String("id", id))
+        respondError(w, err)
+        return
+    }
+
+    respondJSON(w, http.StatusOK, user)
+}
+```
+
+---
+
+## Request Decoding
+
+Use a shared `decodeJSON` helper. Always enforce a size limit on the request
+body to prevent OOM attacks.
+
+```go
+// internal/handler/decode.go
+package handler
+
+import (
+    "encoding/json"
+    "errors"
+    "fmt"
+    "io"
+    "net/http"
+    "strings"
+)
+
+const maxBodyBytes = 1 << 20 // 1 MB
+
+func decodeJSON(r *http.Request, dst any) error {
+    r.Body = http.MaxBytesReader(nil, r.Body, maxBodyBytes)
+    dec := json.NewDecoder(r.Body)
+    dec.DisallowUnknownFields()
+
+    if err := dec.Decode(dst); err != nil {
+        var syntaxErr *json.SyntaxError
+        var unmarshalErr *json.UnmarshalTypeError
+        switch {
+        case errors.As(err, &syntaxErr):
+            return fmt.Errorf("malformed JSON at position %d", syntaxErr.Offset)
+        case errors.As(err, &unmarshalErr):
+            return fmt.Errorf("invalid value for field %q", unmarshalErr.Field)
+        case errors.Is(err, io.EOF):
+            return errors.New("request body must not be empty")
+        case strings.HasPrefix(err.Error(), "json: unknown field"):
+            field := strings.TrimPrefix(err.Error(), "json: unknown field ")
+            return fmt.Errorf("unknown field %s", field)
+        default:
+            return fmt.Errorf("decoding request: %w", err)
+        }
+    }
+    return nil
+}
+```
+
+---
+
+## Response Helpers
+
+All responses use a consistent JSON envelope. Errors always include a
+machine-readable `code` field so clients can branch on it.
+
+```go
+// internal/handler/respond.go
+package handler
+
+import (
+    "encoding/json"
+    "errors"
+    "net/http"
+
+    "github.com/zokypesch/go-ga-lib/internal/domain"
+)
+
+type errorBody struct {
+    Error string `json:"error"`
+    Code  string `json:"code"`
+}
+
+func respondJSON(w http.ResponseWriter, status int, data any) {
+    w.Header().Set("Content-Type", "application/json")
+    w.WriteHeader(status)
+    if data != nil {
+        _ = json.NewEncoder(w).Encode(data)
+    }
+}
+
+func respondError(w http.ResponseWriter, err error) {
+    switch {
+    case errors.Is(err, domain.ErrNotFound):
+        writeErrorBody(w, http.StatusNotFound, err.Error(), "NOT_FOUND")
+    case errors.Is(err, domain.ErrAlreadyExists):
+        writeErrorBody(w, http.StatusConflict, err.Error(), "CONFLICT")
+    case errors.Is(err, domain.ErrInvalidInput):
+        writeErrorBody(w, http.StatusBadRequest, err.Error(), "BAD_REQUEST")
+    case errors.Is(err, domain.ErrUnauthorized):
+        writeErrorBody(w, http.StatusUnauthorized, err.Error(), "UNAUTHORIZED")
+    case errors.Is(err, domain.ErrForbidden):
+        writeErrorBody(w, http.StatusForbidden, err.Error(), "FORBIDDEN")
+    default:
+        writeErrorBody(w, http.StatusInternalServerError, "internal server error", "INTERNAL")
+    }
+}
+
+// respondErrorStatus allows callers to supply an explicit status code + code string
+// (e.g., from decodeJSON where no domain sentinel applies).
+func respondErrorStatus(w http.ResponseWriter, status int, message, code string) {
+    writeErrorBody(w, status, message, code)
+}
+
+func writeErrorBody(w http.ResponseWriter, status int, message, code string) {
+    w.Header().Set("Content-Type", "application/json")
+    w.WriteHeader(status)
+    _ = json.NewEncoder(w).Encode(errorBody{Error: message, Code: code})
+}
+```
+
+---
+
+## Auth Middleware
+
+Request-scoped values travel through `context.Context`. Define typed keys
+(never string keys) to avoid collisions.
+
+```go
+// internal/handler/middleware/auth.go
+package middleware
+
+import (
+    "context"
+    "net/http"
+    "strings"
+)
+
+type contextKey string
+
+const claimsKey contextKey = "claims"
+
+type Claims struct {
+    UserID string
+    Email  string
+    Roles  []string
+}
+
+// BearerAuth validates the Authorization header and stores claims in context.
+func BearerAuth(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        token := strings.TrimPrefix(r.Header.Get("Authorization"), "Bearer ")
+        if token == "" {
+            http.Error(w, `{"error":"missing token","code":"UNAUTHORIZED"}`, http.StatusUnauthorized)
+            return
+        }
+
+        claims, err := validateToken(token)
+        if err != nil {
+            http.Error(w, `{"error":"invalid token","code":"UNAUTHORIZED"}`, http.StatusUnauthorized)
+            return
+        }
+
+        ctx := context.WithValue(r.Context(), claimsKey, claims)
+        next.ServeHTTP(w, r.WithContext(ctx))
+    })
+}
+
+// ClaimsFromContext extracts validated claims — returns false if not present.
+func ClaimsFromContext(ctx context.Context) (*Claims, bool) {
+    c, ok := ctx.Value(claimsKey).(*Claims)
+    return c, ok
+}
+```
+
+Apply per-route group, not globally:
+
+```go
+r.Route("/api/v1", func(r chi.Router) {
+    r.Use(middleware.BearerAuth)  // protects everything under /api/v1
+    r.Mount("/users", userHandler.Routes())
+})
+```
+
+---
+
+## Health and Readiness Endpoints
+
+Every service exposes `/health` (liveness) and `/ready` (readiness). These
+are used by Kubernetes probes and must never be behind auth middleware.
+
+```go
+// internal/handler/health_handler.go
+package handler
+
+import (
+    "context"
+    "database/sql"
+    "net/http"
+    "time"
+)
+
+type HealthHandler struct {
+    db *sql.DB
+}
+
+func NewHealthHandler(db *sql.DB) *HealthHandler {
+    return &HealthHandler{db: db}
+}
+
+// Health is the liveness probe — always 200 if the process is running.
+func (h *HealthHandler) Health(w http.ResponseWriter, r *http.Request) {
+    respondJSON(w, http.StatusOK, map[string]string{"status": "ok"})
+}
+
+// Ready is the readiness probe — 503 if dependencies are not available.
+func (h *HealthHandler) Ready(w http.ResponseWriter, r *http.Request) {
+    ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
+    defer cancel()
+
+    if err := h.db.PingContext(ctx); err != nil {
+        respondJSON(w, http.StatusServiceUnavailable, map[string]string{
+            "status": "not ready",
+            "reason": "database unreachable",
+        })
+        return
+    }
+
+    respondJSON(w, http.StatusOK, map[string]string{"status": "ready"})
+}
+```
+
+---
+
+## Route Grouping Convention
+
+```
+GET    /api/v1/users         → List
+POST   /api/v1/users         → Create
+GET    /api/v1/users/{id}    → Get
+PUT    /api/v1/users/{id}    → Update (full replacement)
+PATCH  /api/v1/users/{id}    → PartialUpdate
+DELETE /api/v1/users/{id}    → Delete
+
+GET    /health               → Health (liveness)
+GET    /ready                → Ready (readiness)
+GET    /metrics              → Prometheus scrape endpoint
+```
+
+---
+
+## DO NOT
+
+```go
+// WRONG: using default ServeMux
+http.HandleFunc("/users", handler)  // WRONG: no URL params, no middleware chaining
+
+// WRONG: business logic in handler
+func (h *UserHandler) Create(w http.ResponseWriter, r *http.Request) {
+    var u domain.User
+    json.NewDecoder(r.Body).Decode(&u)
+    // WRONG: password hashing, email validation, and DB writes directly in handler
+    u.Password = bcrypt.GenerateFromPassword(...)
+    db.Insert(u)
+}
+
+// WRONG: string context keys
+ctx = context.WithValue(ctx, "userID", id)  // WRONG: use typed keys
+
+// WRONG: ignoring Body close / size limit
+json.NewDecoder(r.Body).Decode(&input)  // WRONG: no size limit, no close
+```