code-ai-installer 3.0.0 → 4.0.0

package/domains/development/locales/en/.agents/skills/go-beast-practices-reference/SKILL.md

@@ -0,0 +1,539 @@
+---
+name: go-beast-practices-reference
+description: "Canonical Go code reference — detailed DO/DON'T examples across 7 topics — error handling, interfaces and DI, context, concurrency (errgroup, worker pool, graceful shutdown), HTTP handlers, testing (table-driven), tooling (Makefile, golangci-lint). Activate when looking up a specific code pattern."
+type: reference
+domain: development
+owners:
+  - senior_full_stack
+gates:
+  - DEV
+tech:
+  - go
+topic:
+  - general
+triggers:
+  - Go code example
+  - errgroup example
+  - errors.Is wrap fmt.Errorf
+  - context.WithTimeout Go
+  - Go table-driven test
+  - middleware chain Go
+  - golangci-lint config
+related:
+  - go-beast-practices
+  - node-express-beast-practices-reference
+  - testing-strategy-js
+  - tdd-workflow
+  - security-baseline-dev
+  - observability-logging
+  - dev-reference-snippets
+budget_lines: 750
+schema_version: 1
+---
+
+
+# Skill: Go Code Reference (DO/DON'T)
+
+Canonical reference of Go code patterns. Decision rules + canonical tables — in `$go-beast-practices`.
+
+**Sections:**
+2. [Error Handling](#2-error-handling)
+3. [Interfaces and DI](#3-interfaces-and-di)
+4. [Context](#4-context)
+5. [Concurrency](#5-concurrency)
+6. [HTTP Handlers](#6-http-handlers)
+7. [Testing](#7-testing)
+8. [Tooling](#8-tooling)
+
+> Project structure (`cmd/`, `internal/`, `pkg/`) — in `$go-beast-practices` §1. Anti-patterns table — in `$go-beast-practices` §9.
+
+---
+
+## 2. Error Handling
+
+### ✅ DO: wrap errors with context
+
+```go
+// ✅ fmt.Errorf with %w — preserves the error chain
+func (r *CouponRepo) FindByID(ctx context.Context, id string) (*model.Coupon, error) {
+    var coupon model.Coupon
+    err := r.db.QueryRowContext(ctx, "SELECT * FROM coupons WHERE id = $1", id).Scan(&coupon)
+    if err != nil {
+        if errors.Is(err, sql.ErrNoRows) {
+            return nil, fmt.Errorf("coupon %s: %w", id, ErrNotFound)
+        }
+        return nil, fmt.Errorf("query coupon %s: %w", id, err)
+    }
+    return &coupon, nil
+}
+```
+
+### ✅ DO: sentinel errors for business errors
+
+```go
+// errors.go
+package service
+
+import "errors"
+
+var (
+    ErrNotFound    = errors.New("not found")
+    ErrConflict    = errors.New("already exists")
+    ErrValidation  = errors.New("validation failed")
+    ErrUnauthorized = errors.New("unauthorized")
+)
+
+// In handler:
+func (h *Handler) GetCoupon(w http.ResponseWriter, r *http.Request) {
+    coupon, err := h.service.GetByID(r.Context(), id)
+    if err != nil {
+        switch {
+        case errors.Is(err, service.ErrNotFound):
+            httputil.Error(w, http.StatusNotFound, err.Error())
+        case errors.Is(err, service.ErrUnauthorized):
+            httputil.Error(w, http.StatusUnauthorized, "access denied")
+        default:
+            h.logger.Error("get coupon failed", "error", err, "id", id)
+            httputil.Error(w, http.StatusInternalServerError, "internal error")
+        }
+        return
+    }
+    httputil.JSON(w, http.StatusOK, coupon)
+}
+```
+
+### ❌ DON'T: ignore errors
+
+```go
+// ❌ Error is silently swallowed
+json.Unmarshal(data, &result) // err ignored!
+
+// ✅ Always check
+if err := json.Unmarshal(data, &result); err != nil {
+    return fmt.Errorf("unmarshal response: %w", err)
+}
+
+// ❌ Panic instead of handling
+func MustParse(s string) int {
+    n, err := strconv.Atoi(s)
+    if err != nil {
+        panic(err) // ❌ never in production
+    }
+    return n
+}
+```
+
+---
+
+## 3. Interfaces and DI
+
+### ✅ DO: small interfaces on the consumer side
+
+```go
+// ✅ Interface is defined where it is USED, not where it is implemented
+// service/coupon.go
+type CouponRepository interface {
+    FindByID(ctx context.Context, id string) (*model.Coupon, error)
+    FindAll(ctx context.Context, offset, limit int) ([]model.Coupon, error)
+    Create(ctx context.Context, c *model.Coupon) error
+    Delete(ctx context.Context, id string) error
+}
+
+type CouponService struct {
+    repo   CouponRepository // ✅ dependency on interface
+    logger *slog.Logger
+}
+
+func NewCouponService(repo CouponRepository, logger *slog.Logger) *CouponService {
+    return &CouponService{repo: repo, logger: logger}
+}
+```
+
+### ❌ DON'T: fat interfaces
+
+```go
+// ❌ Interface with 20 methods — impossible to mock, violates ISP
+type Database interface {
+    FindUser(ctx context.Context, id string) (*User, error)
+    FindCoupon(ctx context.Context, id string) (*Coupon, error)
+    FindOrder(ctx context.Context, id string) (*Order, error)
+    CreateUser(...) error
+    CreateCoupon(...) error
+    // ... 15 more methods
+}
+
+// ✅ Small interfaces by domain
+type UserFinder interface {
+    FindUser(ctx context.Context, id string) (*User, error)
+}
+```
+
+---
+
+## 4. Context
+
+### ✅ DO: context as the first parameter
+
+```go
+// ✅ ctx is always first, named ctx
+func (s *CouponService) GetByID(ctx context.Context, id string) (*model.Coupon, error) {
+    return s.repo.FindByID(ctx, id)
+}
+
+// ✅ Timeout via context
+func (h *Handler) ListCoupons(w http.ResponseWriter, r *http.Request) {
+    ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
+    defer cancel()
+
+    coupons, err := h.service.ListAll(ctx)
+    // ...
+}
+
+// ❌ Do not store context in struct
+type BadService struct {
+    ctx context.Context // ❌ context is not stored in structs!
+}
+```
+
+---
+
+## 5. Concurrency
+
+### ✅ DO: errgroup for parallel tasks
+
+```go
+import "golang.org/x/sync/errgroup"
+
+func (s *DashboardService) GetDashboard(ctx context.Context, userID string) (*Dashboard, error) {
+    g, ctx := errgroup.WithContext(ctx)
+
+    var user *model.User
+    var stats *model.Stats
+    var coupons []model.Coupon
+
+    g.Go(func() error {
+        var err error
+        user, err = s.userRepo.FindByID(ctx, userID)
+        return err
+    })
+
+    g.Go(func() error {
+        var err error
+        stats, err = s.statsRepo.GetForUser(ctx, userID)
+        return err
+    })
+
+    g.Go(func() error {
+        var err error
+        coupons, err = s.couponRepo.FindByUser(ctx, userID)
+        return err
+    })
+
+    if err := g.Wait(); err != nil {
+        return nil, fmt.Errorf("load dashboard for %s: %w", userID, err)
+    }
+
+    return &Dashboard{User: user, Stats: stats, Coupons: coupons}, nil
+}
+```
+
+### ✅ DO: worker pool with semaphore
+
+```go
+func processItems(ctx context.Context, items []Item, maxWorkers int) error {
+    g, ctx := errgroup.WithContext(ctx)
+    g.SetLimit(maxWorkers) // ✅ concurrency limit
+
+    for _, item := range items {
+        item := item // ✅ capture (Go < 1.22)
+        g.Go(func() error {
+            return processItem(ctx, item)
+        })
+    }
+
+    return g.Wait()
+}
+```
+
+### ✅ DO: graceful shutdown
+
+```go
+func main() {
+    srv := &http.Server{Addr: ":8080", Handler: mux}
+
+    // Start server in goroutine
+    go func() {
+        if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+            log.Fatal("server error:", err)
+        }
+    }()
+
+    // Wait for signal
+    quit := make(chan os.Signal, 1)
+    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+    <-quit
+
+    log.Println("Shutting down...")
+
+    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+    defer cancel()
+
+    if err := srv.Shutdown(ctx); err != nil {
+        log.Fatal("forced shutdown:", err)
+    }
+
+    log.Println("Server stopped")
+}
+```
+
+---
+
+## 6. HTTP Handlers
+
+### ✅ DO: httputil response helpers
+
+```go
+// pkg/httputil/response.go
+package httputil
+
+import (
+    "encoding/json"
+    "net/http"
+)
+
+// JSON sends a JSON response with the specified status.
+func JSON(w http.ResponseWriter, status int, data any) {
+    w.Header().Set("Content-Type", "application/json")
+    w.WriteHeader(status)
+    json.NewEncoder(w).Encode(data)
+}
+
+// Error sends a JSON error response.
+func Error(w http.ResponseWriter, status int, message string) {
+    JSON(w, status, map[string]string{"error": message})
+}
+```
+
+### ✅ DO: middleware pattern
+
+```go
+// Middleware type
+type Middleware func(http.Handler) http.Handler
+
+// RequestID middleware
+func RequestID(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        id := r.Header.Get("X-Request-ID")
+        if id == "" {
+            id = uuid.NewString()
+        }
+        ctx := context.WithValue(r.Context(), requestIDKey, id)
+        w.Header().Set("X-Request-ID", id)
+        next.ServeHTTP(w, r.WithContext(ctx))
+    })
+}
+
+// Logging middleware
+func Logging(logger *slog.Logger) Middleware {
+    return func(next http.Handler) http.Handler {
+        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+            start := time.Now()
+            ww := &responseWriter{ResponseWriter: w, status: http.StatusOK}
+
+            next.ServeHTTP(ww, r)
+
+            logger.Info("request",
+                "method", r.Method,
+                "path", r.URL.Path,
+                "status", ww.status,
+                "duration", time.Since(start),
+                "request_id", r.Context().Value(requestIDKey),
+            )
+        })
+    }
+}
+
+// Chain middleware
+func Chain(h http.Handler, mw ...Middleware) http.Handler {
+    for i := len(mw) - 1; i >= 0; i-- {
+        h = mw[i](h)
+    }
+    return h
+}
+```
+
+---
+
+## 7. Testing
+
+### ✅ DO: table-driven tests
+
+```go
+func TestCalculateDiscount(t *testing.T) {
+    tests := []struct {
+        name     string
+        price    float64
+        percent  float64
+        want     float64
+        wantErr  bool
+    }{
+        {name: "20% off 100", price: 100, percent: 20, want: 80},
+        {name: "100% off", price: 50, percent: 100, want: 0},
+        {name: "0% off", price: 100, percent: 0, want: 100},
+        {name: "negative price", price: -10, percent: 5, wantErr: true},
+        {name: "discount > 100%", price: 100, percent: 120, wantErr: true},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            got, err := CalculateDiscount(tt.price, tt.percent)
+
+            if tt.wantErr {
+                if err == nil {
+                    t.Fatal("expected error, got nil")
+                }
+                return
+            }
+
+            if err != nil {
+                t.Fatalf("unexpected error: %v", err)
+            }
+            if got != tt.want {
+                t.Errorf("got %v, want %v", got, tt.want)
+            }
+        })
+    }
+}
+```
+
+### ✅ DO: test helpers with t.Helper()
+
+```go
+func createTestCoupon(t *testing.T, db *sql.DB, code string) *model.Coupon {
+    t.Helper() // ✅ errors will show the calling line, not this one
+
+    coupon := &model.Coupon{
+        ID:       uuid.NewString(),
+        Code:     code,
+        Discount: 10,
+        Active:   true,
+    }
+
+    _, err := db.Exec("INSERT INTO coupons (id, code, discount, active) VALUES ($1, $2, $3, $4)",
+        coupon.ID, coupon.Code, coupon.Discount, coupon.Active)
+    if err != nil {
+        t.Fatalf("create test coupon: %v", err)
+    }
+
+    t.Cleanup(func() { // ✅ automatic cleanup
+        db.Exec("DELETE FROM coupons WHERE id = $1", coupon.ID)
+    })
+
+    return coupon
+}
+```
+
+### ✅ DO: HTTP handler tests
+
+```go
+func TestGetCoupon(t *testing.T) {
+    // Arrange
+    mockService := &MockCouponService{
+        GetByIDFn: func(ctx context.Context, id string) (*model.Coupon, error) {
+            return &model.Coupon{ID: id, Code: "TEST10"}, nil
+        },
+    }
+    handler := NewHandler(mockService, slog.Default())
+
+    req := httptest.NewRequest(http.MethodGet, "/coupons/abc", nil)
+    rec := httptest.NewRecorder()
+
+    // Act
+    handler.GetCoupon(rec, req)
+
+    // Assert
+    if rec.Code != http.StatusOK {
+        t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+    }
+
+    var got model.Coupon
+    json.NewDecoder(rec.Body).Decode(&got)
+    if got.Code != "TEST10" {
+        t.Errorf("code = %q, want %q", got.Code, "TEST10")
+    }
+}
+```
+
+---
+
+## 8. Tooling
+
+### Makefile
+
+```makefile
+.PHONY: run test lint fmt build
+
+run:
+	go run ./cmd/server
+
+build:
+	go build -o bin/server ./cmd/server
+
+test:
+	go test -v -race -count=1 ./...
+
+test-cover:
+	go test -coverprofile=coverage.out ./...
+	go tool cover -html=coverage.out -o coverage.html
+
+lint:
+	golangci-lint run ./...
+
+fmt:
+	gofmt -w .
+	goimports -w .
+```
+
+### ✅ DO: golangci-lint config
+
+```yaml
+# .golangci.yml
+linters:
+  enable:
+    - errcheck        # check all errors
+    - govet           # go vet
+    - staticcheck     # powerful static analysis
+    - unused          # unused code
+    - gosimple        # simplifications
+    - ineffassign     # useless assignments
+    - misspell        # typos in comments
+    - gofmt           # formatting
+    - goimports       # import sorting
+    - bodyclose       # unclosed http.Response.Body
+    - contextcheck    # context propagation
+    - nilerr          # return nil after checking err != nil
+
+linters-settings:
+  errcheck:
+    check-blank: true
+  govet:
+    shadow: true
+
+run:
+  timeout: 3m
+
+issues:
+  max-issues-per-linter: 0
+  max-same-issues: 0
+```
+
+---
+
+## See also
+- `$go-beast-practices` — decision rules + anti-patterns table
+- `$node-express-beast-practices-reference` — Node/Express code reference
+- `$testing-strategy-js` — TDD strategy (JS, but patterns are transferable)
+- `$tdd-workflow` — RED→GREEN→REFACTOR
+- `$security-baseline-dev` — security in implementation
+- `$observability-logging` — logging and metrics
+- `$dev-reference-snippets` — general dev examples

package/domains/development/locales/en/.agents/skills/go-beast-practices-reference/agents/claude.json

@@ -0,0 +1,17 @@
+{
+  "name": "go-beast-practices-reference",
+  "display_name": "Go Code Reference (DO/DON'T)",
+  "description": "Canonical Go code reference — detailed DO/DON'T examples across 7 topics — error handling, interfaces and DI, context, concurrency (errgroup, worker pool, graceful shutdown), HTTP handlers, testing (table-driven), tooling (Makefile, golangci-lint). Activate when looking up a specific code pattern."how to properly write X in Go\".",
+  "default_prompt": "Use $go-beast-practices-reference when the task matches the \"Go Code Reference (DO/DON'T)\" skill.",
+  "triggers": [
+    "go-beast-practices-reference",
+    "go beast practices reference",
+    "Go best practices — simplicity, errors as values, interfaces, context, concurrency, project structure, linters, and testing (TDD)"
+  ],
+  "capabilities": [
+    "go",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/go-beast-practices-reference/agents/copilot.json

@@ -0,0 +1,17 @@
+{
+  "name": "go-beast-practices-reference",
+  "display_name": "Go Code Reference (DO/DON'T)",
+  "description": "Canonical Go code reference — detailed DO/DON'T examples across 7 topics — error handling, interfaces and DI, context, concurrency (errgroup, worker pool, graceful shutdown), HTTP handlers, testing (table-driven), tooling (Makefile, golangci-lint). Activate when looking up a specific code pattern."how to properly write X in Go\".",
+  "default_prompt": "Use $go-beast-practices-reference when the task matches the \"Go Code Reference (DO/DON'T)\" skill.",
+  "triggers": [
+    "go-beast-practices-reference",
+    "go beast practices reference",
+    "Go best practices — simplicity, errors as values, interfaces, context, concurrency, project structure, linters, and testing (TDD)"
+  ],
+  "capabilities": [
+    "go",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/go-beast-practices-reference/agents/gemini.json

@@ -0,0 +1,17 @@
+{
+  "name": "go-beast-practices-reference",
+  "display_name": "Go Code Reference (DO/DON'T)",
+  "description": "Canonical Go code reference — detailed DO/DON'T examples across 7 topics — error handling, interfaces and DI, context, concurrency (errgroup, worker pool, graceful shutdown), HTTP handlers, testing (table-driven), tooling (Makefile, golangci-lint). Activate when looking up a specific code pattern."how to properly write X in Go\".",
+  "default_prompt": "Use $go-beast-practices-reference when the task matches the \"Go Code Reference (DO/DON'T)\" skill.",
+  "triggers": [
+    "go-beast-practices-reference",
+    "go beast practices reference",
+    "Go best practices — simplicity, errors as values, interfaces, context, concurrency, project structure, linters, and testing (TDD)"
+  ],
+  "capabilities": [
+    "go",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/go-beast-practices-reference/agents/kimi.yaml

@@ -0,0 +1,13 @@
+name: "go-beast-practices-reference"
+display_name: "Go Code Reference (DO/DON'T)"
+description: "Canonical Go code reference — detailed DO/DON'T examples across 7 topics — error handling, interfaces and DI, context, concurrency (errgroup, worker pool, graceful shutdown), HTTP handlers, testing (table-driven), tooling (Makefile, golangci-lint). Activate when looking up a specific code pattern."how to properly write X in Go\"."
+default_prompt: "Use $go-beast-practices-reference when the task matches the \"Go Code Reference (DO/DON'T)\" skill."
+triggers:
+  - "go-beast-practices-reference"
+  - "go beast practices reference"
+  - "Go best practices — simplicity, errors as values, interfaces, context, concurrency, project structure, linters, and testing (TDD)"
+capabilities:
+  - "go"
+  - "reference"
+tools: []
+implicit_invocation: true

package/domains/development/locales/en/.agents/skills/go-beast-practices-reference/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Go Code Reference (DO/DON'T)"
+  short_description: "Canonical Go code reference — detailed DO/DON'T examples across 7 topics — error handling, interfaces and DI, context, concurrency (errgroup, worker pool, graceful shutdown), HTTP handlers, testing (table-driven), tooling (Makefile, golangci-lint). Activate when looking up a specific code pattern."
+  default_prompt: "Use $go-beast-practices-reference when the task matches the \"Go Code Reference (DO/DON'T)\" skill."
+dependencies:
+  tools: []
+policy:
+  allow_implicit_invocation: true

package/domains/development/locales/en/.agents/skills/go-beast-practices-reference/agents/qwen.json

@@ -0,0 +1,17 @@
+{
+  "name": "go-beast-practices-reference",
+  "display_name": "Go Code Reference (DO/DON'T)",
+  "description": "Canonical Go code reference — detailed DO/DON'T examples across 7 topics — error handling, interfaces and DI, context, concurrency (errgroup, worker pool, graceful shutdown), HTTP handlers, testing (table-driven), tooling (Makefile, golangci-lint). Activate when looking up a specific code pattern."how to properly write X in Go\".",
+  "default_prompt": "Use $go-beast-practices-reference when the task matches the \"Go Code Reference (DO/DON'T)\" skill.",
+  "triggers": [
+    "go-beast-practices-reference",
+    "go beast practices reference",
+    "Go best practices — simplicity, errors as values, interfaces, context, concurrency, project structure, linters, and testing (TDD)"
+  ],
+  "capabilities": [
+    "go",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/go-beast-practices-reference/agents/skill.yaml

@@ -0,0 +1,21 @@
+version: 1
+name: "go-beast-practices-reference"
+display_name: "Go Code Reference (DO/DON'T)"
+description: "Canonical Go code reference — detailed DO/DON'T examples across 7 topics — error handling, interfaces and DI, context, concurrency (errgroup, worker pool, graceful shutdown), HTTP handlers, testing (table-driven), tooling (Makefile, golangci-lint). Activate when looking up a specific code pattern."how to properly write X in Go\"."
+default_prompt: "Use $go-beast-practices-reference when the task matches the \"Go Code Reference (DO/DON'T)\" skill."
+triggers:
+  - "go-beast-practices-reference"
+  - "go beast practices reference"
+  - "Go best practices — simplicity, errors as values, interfaces, context, concurrency, project structure, linters, and testing (TDD)"
+capabilities:
+  - "go"
+  - "reference"
+tools: []
+invocation:
+  explicit: true
+  implicit: true
+localization:
+  default_locale: "en"
+  available_locales:
+    - "ru"
+    - "en"