theus-cli 0.2.83 → 0.2.84

package/vendor/theus-arsenal/skills/patrones-go/SKILL.md

@@ -1,674 +0,0 @@
----
-name: patrones-go
-description: Patrones idiomáticos de Go, buenas prácticas y convenciones para construir aplicaciones robustas, eficientes y mantenibles.
----
-
-# Patrones de desarrollo en Go
-
-Patrones idiomáticos de Go y buenas prácticas para construir aplicaciones robustas, eficientes y mantenibles.
-
-## Cuándo activar esta skill
-
-- Al escribir código Go nuevo
-- Al revisar código Go
-- Al refactorizar código Go existente
-- Al diseñar paquetes/módulos de Go
-
-## Principios fundamentales
-
-### 1. Simplicidad y claridad
-
-Go prefiere la simplicidad sobre la astucia. El código debe ser obvio y fácil de leer.
-
-```go
-// Bien: claro y directo
-func GetUser(id string) (*User, error) {
-    user, err := db.FindUser(id)
-    if err != nil {
-        return nil, fmt.Errorf("get user %s: %w", id, err)
-    }
-    return user, nil
-}
-
-// Mal: excesivamente rebuscado
-func GetUser(id string) (*User, error) {
-    return func() (*User, error) {
-        if u, e := db.FindUser(id); e == nil {
-            return u, nil
-        } else {
-            return nil, e
-        }
-    }()
-}
-```
-
-### 2. Haz útil el valor cero
-
-Diseña los tipos de forma que su valor cero sea usable de inmediato sin inicialización.
-
-```go
-// Bien: el valor cero es útil
-type Counter struct {
-    mu    sync.Mutex
-    count int // el valor cero es 0, listo para usar
-}
-
-func (c *Counter) Inc() {
-    c.mu.Lock()
-    c.count++
-    c.mu.Unlock()
-}
-
-// Bien: bytes.Buffer funciona con su valor cero
-var buf bytes.Buffer
-buf.WriteString("hello")
-
-// Mal: requiere inicialización
-type BadCounter struct {
-    counts map[string]int // un map nil provocará panic
-}
-```
-
-### 3. Acepta interfaces, devuelve structs
-
-Las funciones deben aceptar parámetros de tipo interface y devolver tipos concretos.
-
-```go
-// Bien: acepta una interface, devuelve un tipo concreto
-func ProcessData(r io.Reader) (*Result, error) {
-    data, err := io.ReadAll(r)
-    if err != nil {
-        return nil, err
-    }
-    return &Result{Data: data}, nil
-}
-
-// Mal: devuelve una interface (oculta innecesariamente los detalles de implementación)
-func ProcessData(r io.Reader) (io.Reader, error) {
-    // ...
-}
-```
-
-## Patrones de manejo de errores
-
-### Envolver errores con contexto
-
-```go
-// Bien: envolver los errores con contexto
-func LoadConfig(path string) (*Config, error) {
-    data, err := os.ReadFile(path)
-    if err != nil {
-        return nil, fmt.Errorf("load config %s: %w", path, err)
-    }
-
-    var cfg Config
-    if err := json.Unmarshal(data, &cfg); err != nil {
-        return nil, fmt.Errorf("parse config %s: %w", path, err)
-    }
-
-    return &cfg, nil
-}
-```
-
-### Tipos de error personalizados
-
-```go
-// Definir errores específicos del dominio
-type ValidationError struct {
-    Field   string
-    Message string
-}
-
-func (e *ValidationError) Error() string {
-    return fmt.Sprintf("validation failed on %s: %s", e.Field, e.Message)
-}
-
-// Errores centinela para casos comunes
-var (
-    ErrNotFound     = errors.New("resource not found")
-    ErrUnauthorized = errors.New("unauthorized")
-    ErrInvalidInput = errors.New("invalid input")
-)
-```
-
-### Comprobación de errores con errors.Is y errors.As
-
-```go
-func HandleError(err error) {
-    // Comprobar un error específico
-    if errors.Is(err, sql.ErrNoRows) {
-        log.Println("No se encontraron registros")
-        return
-    }
-
-    // Comprobar el tipo de error
-    var validationErr *ValidationError
-    if errors.As(err, &validationErr) {
-        log.Printf("Error de validación en el campo %s: %s",
-            validationErr.Field, validationErr.Message)
-        return
-    }
-
-    // Error desconocido
-    log.Printf("Error inesperado: %v", err)
-}
-```
-
-### Nunca ignores los errores
-
-```go
-// Mal: ignorar el error con el identificador en blanco
-result, _ := doSomething()
-
-// Bien: manejarlo o documentar explícitamente por qué es seguro ignorarlo
-result, err := doSomething()
-if err != nil {
-    return err
-}
-
-// Aceptable: cuando el error realmente no importa (raro)
-_ = writer.Close() // Limpieza de mejor esfuerzo; el error se registra en otro lugar
-```
-
-## Patrones de concurrencia
-
-### Worker pool
-
-```go
-func WorkerPool(jobs <-chan Job, results chan<- Result, numWorkers int) {
-    var wg sync.WaitGroup
-
-    for i := 0; i < numWorkers; i++ {
-        wg.Add(1)
-        go func() {
-            defer wg.Done()
-            for job := range jobs {
-                results <- process(job)
-            }
-        }()
-    }
-
-    wg.Wait()
-    close(results)
-}
-```
-
-### Context para cancelación y timeouts
-
-```go
-func FetchWithTimeout(ctx context.Context, url string) ([]byte, error) {
-    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
-    defer cancel()
-
-    req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
-    if err != nil {
-        return nil, fmt.Errorf("create request: %w", err)
-    }
-
-    resp, err := http.DefaultClient.Do(req)
-    if err != nil {
-        return nil, fmt.Errorf("fetch %s: %w", url, err)
-    }
-    defer resp.Body.Close()
-
-    return io.ReadAll(resp.Body)
-}
-```
-
-### Apagado ordenado (graceful shutdown)
-
-```go
-func GracefulShutdown(server *http.Server) {
-    quit := make(chan os.Signal, 1)
-    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
-
-    <-quit
-    log.Println("Apagando el servidor...")
-
-    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-    defer cancel()
-
-    if err := server.Shutdown(ctx); err != nil {
-        log.Fatalf("El servidor se vio forzado a apagarse: %v", err)
-    }
-
-    log.Println("Servidor detenido")
-}
-```
-
-### errgroup para goroutines coordinadas
-
-```go
-import "golang.org/x/sync/errgroup"
-
-func FetchAll(ctx context.Context, urls []string) ([][]byte, error) {
-    g, ctx := errgroup.WithContext(ctx)
-    results := make([][]byte, len(urls))
-
-    for i, url := range urls {
-        i, url := i, url // Capturar las variables del bucle
-        g.Go(func() error {
-            data, err := FetchWithTimeout(ctx, url)
-            if err != nil {
-                return err
-            }
-            results[i] = data
-            return nil
-        })
-    }
-
-    if err := g.Wait(); err != nil {
-        return nil, err
-    }
-    return results, nil
-}
-```
-
-### Evitar fugas de goroutines
-
-```go
-// Mal: fuga de goroutine si el contexto se cancela
-func leakyFetch(ctx context.Context, url string) <-chan []byte {
-    ch := make(chan []byte)
-    go func() {
-        data, _ := fetch(url)
-        ch <- data // Se bloquea para siempre si no hay receptor
-    }()
-    return ch
-}
-
-// Bien: maneja correctamente la cancelación
-func safeFetch(ctx context.Context, url string) <-chan []byte {
-    ch := make(chan []byte, 1) // Canal con buffer
-    go func() {
-        data, err := fetch(url)
-        if err != nil {
-            return
-        }
-        select {
-        case ch <- data:
-        case <-ctx.Done():
-        }
-    }()
-    return ch
-}
-```
-
-## Diseño de interfaces
-
-### Interfaces pequeñas y enfocadas
-
-```go
-// Bien: interfaces de un solo método
-type Reader interface {
-    Read(p []byte) (n int, err error)
-}
-
-type Writer interface {
-    Write(p []byte) (n int, err error)
-}
-
-type Closer interface {
-    Close() error
-}
-
-// Componer interfaces según se necesite
-type ReadWriteCloser interface {
-    Reader
-    Writer
-    Closer
-}
-```
-
-### Define las interfaces donde se usan
-
-```go
-// En el paquete consumidor, no en el proveedor
-package service
-
-// UserStore define lo que este servicio necesita
-type UserStore interface {
-    GetUser(id string) (*User, error)
-    SaveUser(user *User) error
-}
-
-type Service struct {
-    store UserStore
-}
-
-// La implementación concreta puede estar en otro paquete
-// No necesita conocer esta interface
-```
-
-### Comportamiento opcional con aserciones de tipo
-
-```go
-type Flusher interface {
-    Flush() error
-}
-
-func WriteAndFlush(w io.Writer, data []byte) error {
-    if _, err := w.Write(data); err != nil {
-        return err
-    }
-
-    // Hacer flush si está soportado
-    if f, ok := w.(Flusher); ok {
-        return f.Flush()
-    }
-    return nil
-}
-```
-
-## Organización de paquetes
-
-### Estructura estándar de proyecto
-
-```text
-myproject/
-├── cmd/
-│   └── myapp/
-│       └── main.go           # Punto de entrada
-├── internal/
-│   ├── handler/              # Handlers HTTP
-│   ├── service/              # Lógica de negocio
-│   ├── repository/           # Acceso a datos
-│   └── config/               # Configuración
-├── pkg/
-│   └── client/               # Cliente de API público
-├── api/
-│   └── v1/                   # Definiciones de API (proto, OpenAPI)
-├── testdata/                 # Fixtures de test
-├── go.mod
-├── go.sum
-└── Makefile
-```
-
-### Nombres de paquetes
-
-```go
-// Bien: cortos, en minúsculas, sin guiones bajos
-package http
-package json
-package user
-
-// Mal: verbosos, con mayúsculas mezcladas o redundantes
-package httpHandler
-package json_parser
-package userService // Sufijo 'Service' redundante
-```
-
-### Evita el estado a nivel de paquete
-
-```go
-// Mal: estado global mutable
-var db *sql.DB
-
-func init() {
-    db, _ = sql.Open("postgres", os.Getenv("DATABASE_URL"))
-}
-
-// Bien: inyección de dependencias
-type Server struct {
-    db *sql.DB
-}
-
-func NewServer(db *sql.DB) *Server {
-    return &Server{db: db}
-}
-```
-
-## Diseño de structs
-
-### Patrón de opciones funcionales
-
-```go
-type Server struct {
-    addr    string
-    timeout time.Duration
-    logger  *log.Logger
-}
-
-type Option func(*Server)
-
-func WithTimeout(d time.Duration) Option {
-    return func(s *Server) {
-        s.timeout = d
-    }
-}
-
-func WithLogger(l *log.Logger) Option {
-    return func(s *Server) {
-        s.logger = l
-    }
-}
-
-func NewServer(addr string, opts ...Option) *Server {
-    s := &Server{
-        addr:    addr,
-        timeout: 30 * time.Second, // valor por defecto
-        logger:  log.Default(),    // valor por defecto
-    }
-    for _, opt := range opts {
-        opt(s)
-    }
-    return s
-}
-
-// Uso
-server := NewServer(":8080",
-    WithTimeout(60*time.Second),
-    WithLogger(customLogger),
-)
-```
-
-### Embedding para composición
-
-```go
-type Logger struct {
-    prefix string
-}
-
-func (l *Logger) Log(msg string) {
-    fmt.Printf("[%s] %s\n", l.prefix, msg)
-}
-
-type Server struct {
-    *Logger // Embedding: Server obtiene el método Log
-    addr    string
-}
-
-func NewServer(addr string) *Server {
-    return &Server{
-        Logger: &Logger{prefix: "SERVER"},
-        addr:   addr,
-    }
-}
-
-// Uso
-s := NewServer(":8080")
-s.Log("Iniciando...") // Llama al Log del Logger embebido
-```
-
-## Memoria y rendimiento
-
-### Prealoca slices cuando el tamaño es conocido
-
-```go
-// Mal: el slice crece varias veces
-func processItems(items []Item) []Result {
-    var results []Result
-    for _, item := range items {
-        results = append(results, process(item))
-    }
-    return results
-}
-
-// Bien: una sola asignación
-func processItems(items []Item) []Result {
-    results := make([]Result, 0, len(items))
-    for _, item := range items {
-        results = append(results, process(item))
-    }
-    return results
-}
-```
-
-### Usa sync.Pool para asignaciones frecuentes
-
-```go
-var bufferPool = sync.Pool{
-    New: func() interface{} {
-        return new(bytes.Buffer)
-    },
-}
-
-func ProcessRequest(data []byte) []byte {
-    buf := bufferPool.Get().(*bytes.Buffer)
-    defer func() {
-        buf.Reset()
-        bufferPool.Put(buf)
-    }()
-
-    buf.Write(data)
-    // Procesar...
-    return buf.Bytes()
-}
-```
-
-### Evita la concatenación de strings en bucles
-
-```go
-// Mal: crea muchas asignaciones de strings
-func join(parts []string) string {
-    var result string
-    for _, p := range parts {
-        result += p + ","
-    }
-    return result
-}
-
-// Bien: una sola asignación con strings.Builder
-func join(parts []string) string {
-    var sb strings.Builder
-    for i, p := range parts {
-        if i > 0 {
-            sb.WriteString(",")
-        }
-        sb.WriteString(p)
-    }
-    return sb.String()
-}
-
-// Mejor aún: usar la biblioteca estándar
-func join(parts []string) string {
-    return strings.Join(parts, ",")
-}
-```
-
-## Integración con las herramientas de Go
-
-### Comandos esenciales
-
-```bash
-# Compilar y ejecutar
-go build ./...
-go run ./cmd/myapp
-
-# Testing
-go test ./...
-go test -race ./...
-go test -cover ./...
-
-# Análisis estático
-go vet ./...
-staticcheck ./...
-golangci-lint run
-
-# Gestión de módulos
-go mod tidy
-go mod verify
-
-# Formateo
-gofmt -w .
-goimports -w .
-```
-
-### Configuración de linter recomendada (.golangci.yml)
-
-```yaml
-linters:
-  enable:
-    - errcheck
-    - gosimple
-    - govet
-    - ineffassign
-    - staticcheck
-    - unused
-    - gofmt
-    - goimports
-    - misspell
-    - unconvert
-    - unparam
-
-linters-settings:
-  errcheck:
-    check-type-assertions: true
-  govet:
-    enable:
-      - shadow
-
-issues:
-  exclude-use-default: false
-```
-
-## Referencia rápida: modismos de Go
-
-| Modismo | Descripción |
-|---------|-------------|
-| Acepta interfaces, devuelve structs | Las funciones aceptan parámetros de interface y devuelven tipos concretos |
-| Los errores son valores | Trata los errores como valores de primera clase, no como excepciones |
-| No te comuniques compartiendo memoria | Usa canales para coordinar goroutines |
-| Haz útil el valor cero | Los tipos deben funcionar sin inicialización explícita |
-| Un poco de copia es mejor que un poco de dependencia | Evita dependencias externas innecesarias |
-| Claro es mejor que ingenioso | Prioriza la legibilidad sobre la astucia |
-| gofmt no es el favorito de nadie pero es amigo de todos | Formatea siempre con gofmt/goimports |
-| Retorna temprano | Maneja los errores primero, mantén el camino feliz sin indentar |
-
-## Antipatrones a evitar
-
-```go
-// Mal: naked returns en funciones largas
-func process() (result int, err error) {
-    // ... 50 líneas ...
-    return // ¿Qué se está devolviendo?
-}
-
-// Mal: usar panic como control de flujo
-func GetUser(id string) *User {
-    user, err := db.Find(id)
-    if err != nil {
-        panic(err) // No hagas esto
-    }
-    return user
-}
-
-// Mal: pasar el contexto dentro de un struct
-type Request struct {
-    ctx context.Context // El contexto debe ser el primer parámetro
-    ID  string
-}
-
-// Bien: contexto como primer parámetro
-func ProcessRequest(ctx context.Context, id string) error {
-    // ...
-}
-
-// Mal: mezclar receptores por valor y por puntero
-type Counter struct{ n int }
-func (c Counter) Value() int { return c.n }    // Receptor por valor
-func (c *Counter) Increment() { c.n++ }        // Receptor por puntero
-// Elige un estilo y sé consistente
-```
-
-**Recuerda**: el código Go debe ser aburrido en el mejor sentido: predecible, consistente y fácil de entender. Ante la duda, mantenlo simple.