ga-plugins-cli 0.1.0 → 0.1.2

package/plugins/go-standards/skills/logging-observability.md

@@ -0,0 +1,340 @@
+# Logging and Observability Standard
+
+The observability stack is Grafana + Prometheus + Loki + Tempo. Every
+service must emit structured logs (JSON → Loki), Prometheus metrics, and
+OpenTelemetry traces (→ Tempo) with trace IDs correlated across all three.
+
+---
+
+## Structured Logging with zap
+
+Use `go.uber.org/zap` in production mode. JSON output is required for Loki
+ingestion. Never use `fmt.Println`, `log.Println`, or `log.Printf` in
+production code paths.
+
+### Logger initialization
+
+```go
+// cmd/server/main.go
+import "go.uber.org/zap"
+
+func buildLogger(level, serviceName, serviceVersion string) (*zap.Logger, error) {
+    cfg := zap.NewProductionConfig()
+
+    // Parse level
+    var zapLevel zap.AtomicLevel
+    if err := zapLevel.UnmarshalText([]byte(level)); err != nil {
+        return nil, fmt.Errorf("invalid log level %q: %w", level, err)
+    }
+    cfg.Level = zapLevel
+
+    // Always add service-level fields for Loki label extraction
+    cfg.InitialFields = map[string]interface{}{
+        "service": serviceName,
+        "version": serviceVersion,
+    }
+
+    logger, err := cfg.Build()
+    if err != nil {
+        return nil, fmt.Errorf("building logger: %w", err)
+    }
+    return logger, nil
+}
+```
+
+### Passing the logger
+
+Pass `*zap.Logger` via constructor — never use a global logger variable.
+
+```go
+repo   := repository.NewUserRepository(db, logger)
+uc     := usecase.NewUserUsecase(repo, logger)
+h      := handler.NewUserHandler(uc, logger)
+```
+
+---
+
+## Log Levels
+
+| Level | When to use |
+|-------|-------------|
+| `Error` | Something went wrong that requires operator attention. Always include `zap.Error(err)`. |
+| `Warn`  | Degraded state — the service is working but something is off (retries, fallback used). |
+| `Info`  | Business-significant events (user created, order placed, payment processed). |
+| `Debug` | Developer-oriented detail (SQL queries, cache hits). Disabled in production. |
+
+### DO
+
+```go
+// Error — actionable failure with structured context
+logger.Error("create user failed",
+    zap.Error(err),
+    zap.String("email", input.Email),
+    zap.String("request_id", requestID),
+    zap.String("trace_id", traceID),
+)
+
+// Info — business event, structured fields
+logger.Info("user created",
+    zap.String("user_id", user.ID),
+    zap.String("email", user.Email),
+    zap.Duration("duration", time.Since(start)),
+)
+
+// Warn — degraded but continuing
+logger.Warn("cache miss, falling back to db",
+    zap.String("key", cacheKey),
+    zap.Duration("cache_latency", latency),
+)
+
+// Debug — dev only, never in prod
+logger.Debug("executing sql",
+    zap.String("query", query),
+    zap.Any("args", args),
+)
+```
+
+### DO NOT
+
+```go
+fmt.Println("user created: " + user.ID)  // WRONG: unstructured, lost in Loki
+log.Printf("error: %v", err)             // WRONG: unstructured stdlib log
+logger.Info(fmt.Sprintf("user %s created", id))  // WRONG: interpolated string not queryable
+logger.Error("something went wrong")     // WRONG: no zap.Error(err), not actionable
+```
+
+---
+
+## Trace ID Correlation
+
+Every log entry for a request must include the trace ID so Grafana can link
+Loki logs to a Tempo trace. Extract the trace ID from the span and inject it
+into a child logger at the handler level.
+
+```go
+// internal/handler/user_handler.go
+import (
+    "go.opentelemetry.io/otel/trace"
+    "go.uber.org/zap"
+)
+
+func (h *UserHandler) Create(w http.ResponseWriter, r *http.Request) {
+    ctx := r.Context()
+    span := trace.SpanFromContext(ctx)
+    traceID := span.SpanContext().TraceID().String()
+
+    // Create a request-scoped logger with trace_id baked in
+    log := h.logger.With(
+        zap.String("trace_id", traceID),
+        zap.String("request_id", middleware.GetReqID(ctx)),
+    )
+
+    user, err := h.uc.Create(ctx, input)
+    if err != nil {
+        log.Error("create user", zap.Error(err))
+        respondError(w, err)
+        return
+    }
+
+    log.Info("user created", zap.String("user_id", user.ID))
+    respondJSON(w, http.StatusCreated, user)
+}
+```
+
+---
+
+## Prometheus Metrics
+
+Register metrics at package init. Use the naming convention
+`<service>_<subsystem>_<name>_<unit>`.
+
+```go
+// internal/metrics/metrics.go
+package metrics
+
+import (
+    "github.com/prometheus/client_golang/prometheus"
+    "github.com/prometheus/client_golang/prometheus/promauto"
+)
+
+var (
+    HTTPRequestsTotal = promauto.NewCounterVec(
+        prometheus.CounterOpts{
+            Name: "user_service_http_requests_total",
+            Help: "Total number of HTTP requests by method, path, and status.",
+        },
+        []string{"method", "path", "status"},
+    )
+
+    HTTPRequestDuration = promauto.NewHistogramVec(
+        prometheus.HistogramOpts{
+            Name:    "user_service_http_duration_seconds",
+            Help:    "HTTP request duration in seconds.",
+            Buckets: prometheus.DefBuckets, // .005 .01 .025 .05 .1 .25 .5 1 2.5 5 10
+        },
+        []string{"method", "path"},
+    )
+
+    ActiveConnections = promauto.NewGauge(prometheus.GaugeOpts{
+        Name: "user_service_active_connections",
+        Help: "Number of active HTTP connections.",
+    })
+
+    DBQueryDuration = promauto.NewHistogramVec(
+        prometheus.HistogramOpts{
+            Name:    "user_service_db_query_duration_seconds",
+            Help:    "Database query duration in seconds.",
+            Buckets: []float64{.001, .005, .01, .025, .05, .1, .5, 1},
+        },
+        []string{"operation", "table"},
+    )
+)
+```
+
+### Metrics middleware
+
+```go
+// internal/handler/middleware/metrics.go
+package middleware
+
+import (
+    "net/http"
+    "strconv"
+    "time"
+
+    "github.com/go-chi/chi/v5"
+    chimiddleware "github.com/go-chi/chi/v5/middleware"
+
+    "github.com/zokypesch/go-ga-lib/internal/metrics"
+)
+
+func PrometheusMetrics(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        start := time.Now()
+        ww := chimiddleware.NewWrapResponseWriter(w, r.ProtoMajor)
+
+        next.ServeHTTP(ww, r)
+
+        routePattern := chi.RouteContext(r.Context()).RoutePattern()
+        duration := time.Since(start).Seconds()
+        status := strconv.Itoa(ww.Status())
+
+        metrics.HTTPRequestsTotal.WithLabelValues(r.Method, routePattern, status).Inc()
+        metrics.HTTPRequestDuration.WithLabelValues(r.Method, routePattern).Observe(duration)
+    })
+}
+```
+
+---
+
+## OpenTelemetry Tracing (→ Tempo)
+
+```go
+// config/otel.go
+package config
+
+import (
+    "context"
+    "fmt"
+
+    "go.opentelemetry.io/otel"
+    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
+    "go.opentelemetry.io/otel/propagation"
+    "go.opentelemetry.io/otel/sdk/resource"
+    sdktrace "go.opentelemetry.io/otel/sdk/trace"
+    semconv "go.opentelemetry.io/otel/semconv/v1.26.0"
+)
+
+func InitTracer(ctx context.Context, endpoint, serviceName, serviceVersion string) (func(context.Context) error, error) {
+    exporter, err := otlptracehttp.New(ctx,
+        otlptracehttp.WithEndpoint(endpoint),
+        otlptracehttp.WithInsecure(),
+    )
+    if err != nil {
+        return nil, fmt.Errorf("creating OTLP exporter: %w", err)
+    }
+
+    res, err := resource.New(ctx,
+        resource.WithAttributes(
+            semconv.ServiceName(serviceName),
+            semconv.ServiceVersion(serviceVersion),
+        ),
+    )
+    if err != nil {
+        return nil, fmt.Errorf("creating resource: %w", err)
+    }
+
+    tp := sdktrace.NewTracerProvider(
+        sdktrace.WithBatcher(exporter),
+        sdktrace.WithResource(res),
+    )
+
+    otel.SetTracerProvider(tp)
+    otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(
+        propagation.TraceContext{},
+        propagation.Baggage{},
+    ))
+
+    return tp.Shutdown, nil
+}
+```
+
+### Using spans in usecases
+
+```go
+// internal/usecase/user_usecase.go
+import "go.opentelemetry.io/otel"
+
+var tracer = otel.Tracer("user-service/usecase")
+
+func (uc *UserUsecase) Create(ctx context.Context, input domain.CreateUserInput) (*domain.User, error) {
+    ctx, span := tracer.Start(ctx, "UserUsecase.Create")
+    defer span.End()
+
+    span.SetAttributes(
+        attribute.String("user.email", input.Email),
+    )
+
+    user, err := uc.repo.Create(ctx, &domain.User{Email: input.Email})
+    if err != nil {
+        span.RecordError(err)
+        span.SetStatus(codes.Error, err.Error())
+        return nil, fmt.Errorf("create user: %w", err)
+    }
+
+    span.SetAttributes(attribute.String("user.id", user.ID))
+    return user, nil
+}
+```
+
+---
+
+## Standard Metric Naming
+
+```
+<service_name>_http_requests_total          counter   {method, path, status}
+<service_name>_http_duration_seconds        histogram {method, path}
+<service_name>_active_connections           gauge
+<service_name>_db_query_duration_seconds    histogram {operation, table}
+<service_name>_cache_hits_total             counter   {cache}
+<service_name>_cache_misses_total           counter   {cache}
+<service_name>_external_calls_total         counter   {service, operation, status}
+<service_name>_external_call_duration_seconds histogram {service, operation}
+```
+
+---
+
+## DO NOT
+
+```go
+fmt.Println("user created")                           // WRONG: unstructured
+log.Println("error:", err)                            // WRONG: stdlib log
+logger.Info("user " + id + " created")                // WRONG: interpolated, not queryable
+logger.Error("failed")                                // WRONG: no zap.Error(err)
+prometheus.MustRegister(counter)                      // WRONG in tests — use promauto in prod
+// WRONG: registering metrics inside a function called per request
+func (h *Handler) Create(...) {
+    counter := prometheus.NewCounter(...)  // WRONG: re-registers every call, panics
+    prometheus.MustRegister(counter)
+}
+```

package/plugins/go-standards/skills/naming-and-style.md

@@ -0,0 +1,315 @@
+# Naming and Style Standard
+
+Go naming conventions differ fundamentally from Java. This skill maps the
+Java patterns you know to their idiomatic Go equivalents, and calls out the
+anti-patterns that must not appear in migrated code.
+
+---
+
+## Package Names
+
+Packages are lowercase, single words, no underscores, no plurals.
+The package name IS the namespace — it will prefix every exported name at
+the call site, so make the combination read naturally.
+
+### DO
+
+```
+handler     not handlerService, not handlers
+usecase     not useCaseService, not use_case
+repository  not repositoryLayer, not repo_layer (repo is acceptable as abbreviation)
+domain      not models, not entities, not dto
+config      not configuration, not conf_loader
+```
+
+```go
+// Reads naturally: handler.NewUserHandler, usecase.NewUserUsecase
+package handler
+package usecase
+package repository
+package domain
+package config
+package metrics
+```
+
+### DO NOT
+
+```go
+package handlerService   // WRONG: redundant suffix
+package userHandlers     // WRONG: plural and redundant
+package util             // WRONG: meaningless catch-all
+package common           // WRONG: a dumping ground
+package helpers          // WRONG: Java holdover
+package base             // WRONG: no abstract base classes in Go
+```
+
+---
+
+## Exported Type Names
+
+Types are nouns. Service types include their role only when it disambiguates.
+
+### DO
+
+```go
+type User struct { ... }
+type Order struct { ... }
+type UserHandler struct { ... }    // Handler suffix is the role — ok
+type UserUsecase struct { ... }    // Usecase suffix distinguishes from domain.User — ok
+type UserRepository struct { ... } // Repository suffix distinguishes from domain.User — ok
+```
+
+### DO NOT
+
+```go
+type UserManager struct { ... }    // WRONG: Manager = vague, Java-ism
+type UserHelper struct { ... }     // WRONG: Helper = vague
+type UserUtil struct { ... }       // WRONG: Util = vague
+type AbstractUser struct { ... }   // WRONG: no abstract classes
+type BaseHandler struct { ... }    // WRONG: use composition, not inheritance
+type IUserRepository interface { } // WRONG: I prefix is C#/Java; Go uses plain names
+```
+
+---
+
+## Interface Naming
+
+Single-method interfaces: method name + `er`.
+Multi-method interfaces: describe the capability as a noun phrase.
+
+### DO
+
+```go
+type Storer interface {
+    Store(ctx context.Context, key string, value []byte) error
+}
+
+type Reader interface {
+    Read(ctx context.Context, key string) ([]byte, error)
+}
+
+type ReadWriter interface {
+    Reader
+    Writer
+}
+
+// Domain repository — multi-method, describes the contract
+type UserRepository interface {
+    FindByID(ctx context.Context, id string) (*User, error)
+    Create(ctx context.Context, u *User) (*User, error)
+    Update(ctx context.Context, u *User) error
+    Delete(ctx context.Context, id string) error
+}
+
+// Domain usecase — multi-method
+type UserUsecase interface {
+    Get(ctx context.Context, id string) (*User, error)
+    Create(ctx context.Context, input CreateUserInput) (*User, error)
+}
+```
+
+### DO NOT
+
+```go
+type IUserRepository interface { ... }  // WRONG: I prefix (Java/C#)
+type UserRepositoryInterface interface { ... }  // WRONG: Interface suffix
+type AbstractUserService interface { ... }  // WRONG: Abstract prefix
+```
+
+---
+
+## Receiver Names
+
+Short, consistent, based on the type name. Never use `self` or `this`.
+
+### DO
+
+```go
+type UserHandler struct { ... }
+func (h *UserHandler) Create(...)  { }  // h for Handler
+func (h *UserHandler) Get(...)     { }  // consistent across all methods
+
+type UserUsecase struct { ... }
+func (uc *UserUsecase) Create(...) { }  // uc for Usecase
+
+type userRepository struct { ... }
+func (r *userRepository) Create(...) { }  // r for Repository
+```
+
+### DO NOT
+
+```go
+func (self *UserHandler) Create(...)  { }  // WRONG: self is Python
+func (this *UserHandler) Create(...)  { }  // WRONG: this is Java/C++
+func (userHandler *UserHandler) Create(...) { }  // WRONG: too verbose
+func (u *UserHandler) Create(...)  { }  // WRONG: u is also used for *User — ambiguous
+```
+
+---
+
+## Constructor Naming
+
+Always `NewX`. Returns `*X` and optionally an error if initialization can fail.
+
+### DO
+
+```go
+// Simple — no error possible
+func NewUserHandler(uc domain.UserUsecase, logger *zap.Logger) *UserHandler {
+    return &UserHandler{uc: uc, logger: logger}
+}
+
+// Complex — returns error if init can fail
+func NewUserRepository(db *sql.DB) (*userRepository, error) {
+    if db == nil {
+        return nil, errors.New("db must not be nil")
+    }
+    if err := db.Ping(); err != nil {
+        return nil, fmt.Errorf("pinging db: %w", err)
+    }
+    return &userRepository{db: db}, nil
+}
+```
+
+### DO NOT
+
+```go
+func CreateUserHandler(...) *UserHandler { }      // WRONG: Create prefix
+func BuildUserHandler(...) *UserHandler { }       // WRONG: Build prefix (use Builder pattern only when warranted)
+func GetUserHandler(...) *UserHandler { }         // WRONG: Get prefix
+func MakeUserHandler(...) *UserHandler { }        // WRONG: Make prefix (reserved for make() built-in)
+func UserHandlerFactory(...) *UserHandler { }     // WRONG: Factory suffix
+```
+
+---
+
+## No Getters and Setters
+
+Go structs expose fields directly unless access control or lazy
+initialization requires otherwise. Getters named `GetFoo()` are a Java
+habit; write `Foo()` if an accessor is needed at all.
+
+### DO
+
+```go
+type User struct {
+    ID    string
+    Email string
+    Name  string
+}
+
+// Direct field access — idiomatic
+user.Email = "new@example.com"
+fmt.Println(user.Name)
+
+// Method with meaning — not a getter
+func (u *User) DisplayName() string {
+    if u.Name != "" {
+        return u.Name
+    }
+    return u.Email
+}
+```
+
+### DO NOT
+
+```go
+// WRONG: Java-style getters/setters
+func (u *User) GetID() string      { return u.ID }    // WRONG
+func (u *User) SetID(id string)    { u.ID = id }      // WRONG
+func (u *User) GetEmail() string   { return u.Email } // WRONG
+func (u *User) SetEmail(e string)  { u.Email = e }    // WRONG
+```
+
+Exception: implement the `fmt.Stringer` interface as `String()`, not
+`ToString()`. Implement `json.Marshaler` as `MarshalJSON()`, etc. Standard
+library interface methods are exempt from the no-getter rule.
+
+---
+
+## No Abstract Base Classes — Use Composition
+
+Go has no inheritance. Share behavior via interfaces and embedding, not
+abstract classes.
+
+### DO
+
+```go
+// Shared logging behavior via embedding
+type baseHandler struct {
+    logger *zap.Logger
+}
+
+func (b *baseHandler) logError(ctx context.Context, op string, err error) {
+    b.logger.Error(op, zap.Error(err), zap.String("request_id", middleware.GetReqID(ctx)))
+}
+
+type UserHandler struct {
+    baseHandler         // embedded — inherits logError
+    uc domain.UserUsecase
+}
+
+type OrderHandler struct {
+    baseHandler
+    oc domain.OrderUsecase
+}
+```
+
+### DO NOT
+
+```go
+// WRONG: Java-style abstract base
+type AbstractHandler struct {
+    logger *zap.Logger
+}
+// Extending via struct embedding is fine — naming it Abstract is not
+```
+
+---
+
+## File Organization
+
+One file per major type. Split by responsibility, not by pattern.
+
+### DO
+
+```
+internal/handler/
+  user_handler.go       // UserHandler and its methods
+  order_handler.go      // OrderHandler and its methods
+  health_handler.go     // HealthHandler
+  respond.go            // shared response helpers
+  decode.go             // shared decoding helpers
+  middleware/
+    auth.go
+    metrics.go
+```
+
+### DO NOT
+
+```
+internal/handler/
+  handlers.go           // WRONG: all handlers in one file
+  interfaces.go         // WRONG: don't separate interfaces into their own file
+  models.go             // WRONG: models belong in domain/
+  utils.go              // WRONG: no utils files
+```
+
+---
+
+## Quick Reference: Java Anti-Pattern → Go Idiomatic
+
+| Java anti-pattern | Go idiom |
+|-------------------|----------|
+| `UserManager` class | `UserUsecase` or inline in handler |
+| `UserHelper` / `UserUtil` | function in the package that uses it |
+| `AbstractBaseHandler` | embedded struct (unnamed or descriptively named) |
+| `IUserRepository` interface | `UserRepository` interface (no I prefix) |
+| `getUserById()` method | `Get` method or `FindByID` method |
+| `setEmail(String email)` | `user.Email = email` |
+| `UserDTO` / `UserVO` | input/output structs inline: `CreateUserInput`, `UserResponse` |
+| `UserServiceImpl` | `userUsecase` (unexported concrete, exported interface) |
+| `@Override` method | satisfies interface implicitly — no annotation |
+| `final` field | unexported field or struct value semantics |
+| `Optional<User>` | `(*User, error)` return pair |
+| `@Builder` (Lombok) | functional options (`WithTimeout`) or plain struct literal |