@coralai/sps-cli 0.41.2 → 0.43.0

package/skills/golang/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: golang
+description: Go language skill — idioms, errors, concurrency, testing. Pair with end skills (`backend`, `devops`) for architecture and with `coding-standards` for cross-language principles.
+origin: ecc-fork + original (https://github.com/affaan-m/everything-claude-code, MIT)
+---
+
+# Go
+
+Go is small on purpose. Few idioms, clear conventions, one canonical way to do most things. Fight the language less, follow its grain more.
+
+## When to load
+
+- Project primary language is Go
+- Reviewing Go code
+- Designing packages, interfaces, error types
+- Concurrency with goroutines, channels, `context.Context`
+
+## Core principles
+
+1. **Clear over clever.** Short functions, short files, short package names.
+2. **Return errors; never panic at API boundaries.** Panics are for unrecoverable bugs, not flow control.
+3. **Accept interfaces, return structs.** The caller owns the abstraction.
+4. **Interfaces live at the call site** (consumer-defined). Don't define an interface until you have two implementations or a test double.
+5. **`context.Context` as the first parameter** on anything that does I/O or can be cancelled.
+6. **Goroutines need a lifecycle.** Every `go f()` needs a story: how it stops, who waits, what happens on error.
+7. **No hidden control flow.** No macros, no implicit constructors, no `this`. If it runs, it's in the code you see.
+8. **Format with `gofmt`.** Style is not a discussion.
+
+## How to use references
+
+| Reference | When to load |
+|---|---|
+| [`references/idioms.md`](references/idioms.md) | Package layout, naming, zero values, struct embedding, slices vs. arrays |
+| [`references/errors.md`](references/errors.md) | `error` interface, wrapping (`%w`), `errors.Is/As`, sentinel vs. typed errors |
+| [`references/concurrency.md`](references/concurrency.md) | Goroutines, channels, `sync`, `context.Context`, cancellation, `errgroup` |
+| [`references/testing.md`](references/testing.md) | `testing` package, table-driven tests, `t.Run`, `testify`, fuzzing, benchmarks |
+
+## Forbidden patterns (auto-reject)
+
+- `panic` outside of `init()` or truly unrecoverable state
+- Ignoring errors with `_`, except in narrow documented cases
+- Goroutines without a cancellation path / termination contract
+- Blocking operations without `context.Context`
+- Interface defined in the package that provides the implementation (should live at call site)
+- `init()` doing I/O or mutating globals
+- Returning named result parameters just to "save" a `return` statement
+- Global mutable state for business data (singletons, package-level vars)
+- Allocating in a hot loop when `sync.Pool` or preallocation would fix it
+- Using `interface{}` / `any` when a concrete type is known

package/skills/golang/references/concurrency.md

@@ -0,0 +1,284 @@
+# Go — Concurrency
+
+Goroutines, channels, `sync`, `context.Context`, `errgroup`.
+
+## The rules
+
+1. Every goroutine must have a way to terminate.
+2. Every blocking operation takes a `context.Context`.
+3. Channels are for communication, not for every synchronization need. `sync.Mutex` and `sync.WaitGroup` are first-class tools.
+4. "Do not communicate by sharing memory; share memory by communicating" is a guideline, not a law. Use what fits.
+
+## `context.Context`
+
+First parameter, always.
+
+```go
+func (s *Service) Get(ctx context.Context, id string) (*User, error) {
+    // pass ctx to every I/O call
+    row := s.db.QueryRowContext(ctx, "select ... where id=$1", id)
+    ...
+}
+```
+
+Responsibilities:
+- **Cancellation** — `<-ctx.Done()` fires when the parent cancels.
+- **Deadline** — `context.WithTimeout(ctx, 5*time.Second)`.
+- **Request-scoped values** — small, process-wide identifiers (trace id, auth principal). NOT a general DI container.
+
+Rules:
+- Never store a context in a struct.
+- Never pass `nil` context; use `context.TODO()` if you really don't have one yet (and fix it).
+- Never ignore a cancelled context and continue — return the error.
+
+## Goroutine lifecycle
+
+```go
+// ❌ detached; we have no way to stop or wait
+go doWork()
+
+// ✅ bounded by context; caller decides when we stop
+go func() {
+    for {
+        select {
+        case <-ctx.Done():
+            return
+        case <-ticker.C:
+            doWork()
+        }
+    }
+}()
+```
+
+Rule: if you spawn a goroutine, write down (in a comment or a test) how it exits.
+
+## WaitGroups
+
+For "wait for N goroutines to finish".
+
+```go
+var wg sync.WaitGroup
+for _, x := range xs {
+    wg.Add(1)
+    go func(x T) {
+        defer wg.Done()
+        process(x)
+    }(x)
+}
+wg.Wait()
+```
+
+Don't call `wg.Add` from inside the goroutine (race). Add before `go`.
+
+## `errgroup` — WaitGroup + errors + cancellation
+
+`golang.org/x/sync/errgroup` is the right default for concurrent work that can fail.
+
+```go
+import "golang.org/x/sync/errgroup"
+
+g, ctx := errgroup.WithContext(ctx)
+for _, url := range urls {
+    url := url                    // shadow (pre-Go-1.22)
+    g.Go(func() error {
+        return fetch(ctx, url)
+    })
+}
+if err := g.Wait(); err != nil {
+    return err                     // first error; ctx is cancelled → others stop
+}
+```
+
+Bounded concurrency:
+```go
+g.SetLimit(10)                     // max 10 in flight
+```
+
+## Channels — send, receive, close
+
+```go
+ch := make(chan int, 10)           // buffered
+
+go func() {
+    defer close(ch)                // signal "no more values"
+    for i := 0; i < 5; i++ {
+        select {
+        case ch <- i:
+        case <-ctx.Done():
+            return                  // unblock on cancellation
+        }
+    }
+}()
+
+for v := range ch {                // exits when ch is closed
+    use(v)
+}
+```
+
+Rules:
+- **The sender closes**, never the receiver.
+- Closing a nil or already-closed channel panics.
+- Receive on a closed channel returns the zero value immediately; use `v, ok := <-ch` to detect close.
+- A `send` on an unbuffered channel blocks until a receiver is ready. That's the synchronization.
+
+## `select` — wait on multiple channels
+
+```go
+select {
+case v := <-ch:
+    handle(v)
+case <-ctx.Done():
+    return ctx.Err()
+case <-time.After(1 * time.Second):
+    return fmt.Errorf("timeout")
+}
+```
+
+`default:` makes `select` non-blocking:
+```go
+select {
+case ch <- v:
+default:
+    // drop; receiver not ready
+}
+```
+
+## Fan-out, fan-in
+
+```go
+func pipeline(ctx context.Context, in <-chan T) <-chan R {
+    out := make(chan R)
+    var wg sync.WaitGroup
+    for i := 0; i < runtime.NumCPU(); i++ {
+        wg.Add(1)
+        go func() {
+            defer wg.Done()
+            for v := range in {
+                select {
+                case out <- process(v):
+                case <-ctx.Done():
+                    return
+                }
+            }
+        }()
+    }
+    go func() { wg.Wait(); close(out) }()
+    return out
+}
+```
+
+Always ensure the downstream can drain — otherwise workers block on send forever after cancellation.
+
+## Mutex vs. channels — pick the right tool
+
+| Need | Use |
+|---|---|
+| Protect a shared map / counter / cache | `sync.Mutex` / `sync.RWMutex` |
+| Protect a single value, read-heavy | `atomic.Value` / `sync/atomic` |
+| Signal "done" / "stop" | close(chan) or `context` |
+| Coordinate N workers on a job queue | channel as queue |
+| One-time init | `sync.Once` |
+| Pool of reusable objects (buffers) | `sync.Pool` |
+
+Don't use channels for what a mutex does better (protect a map). Channels shine for flow and signalling.
+
+## RWMutex
+
+For read-heavy structures.
+
+```go
+type Cache struct {
+    mu   sync.RWMutex
+    data map[string]V
+}
+func (c *Cache) Get(k string) (V, bool) {
+    c.mu.RLock(); defer c.mu.RUnlock()
+    v, ok := c.data[k]
+    return v, ok
+}
+func (c *Cache) Set(k string, v V) {
+    c.mu.Lock(); defer c.mu.Unlock()
+    c.data[k] = v
+}
+```
+
+Don't use `RWMutex` if writes dominate; the overhead makes plain `Mutex` faster.
+
+## `sync.Once`, `sync.Pool`
+
+```go
+var (
+    once  sync.Once
+    cfg   *Config
+)
+func getConfig() *Config {
+    once.Do(func() { cfg = loadConfig() })
+    return cfg
+}
+
+var bufPool = sync.Pool{ New: func() any { return new(bytes.Buffer) } }
+func use() {
+    b := bufPool.Get().(*bytes.Buffer)
+    defer func() { b.Reset(); bufPool.Put(b) }()
+    ...
+}
+```
+
+`sync.Pool` for high-allocation-pressure paths. Don't pool everything — usually you're just adding complexity.
+
+## Race detector
+
+Run tests with `-race` in CI. It catches concurrent reads/writes that break invariants.
+
+```
+go test -race ./...
+```
+
+Cost: ~2-10× slowdown. Only for tests, not prod.
+
+## Common patterns
+
+### Timeout one operation
+
+```go
+ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+defer cancel()
+result, err := slowOp(ctx)
+```
+
+### Heartbeat / leader lock renew
+
+```go
+t := time.NewTicker(15 * time.Second)
+defer t.Stop()
+for {
+    select {
+    case <-ctx.Done(): return
+    case <-t.C:       renew()
+    }
+}
+```
+
+### Worker pool with backpressure
+
+```go
+jobs := make(chan Job, 100)
+for i := 0; i < 10; i++ {
+    go worker(ctx, jobs)
+}
+// producers send on jobs; buffer provides backpressure
+```
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `go f()` with no way to stop | Take `ctx.Context`; return on `<-ctx.Done()` |
+| Reading from a channel with no timeout / cancel | `select { case v := <-ch: case <-ctx.Done(): }` |
+| Closing a channel from the receiver | Only the sender closes |
+| Sharing a `sync.Mutex` by value | Copy breaks locking — always by pointer |
+| `for { select { default: ... } }` busy loop | Add a timer / cancel; don't spin |
+| Global mutable maps without a mutex | Wrap in a type with a lock |
+| Ignoring `context.Canceled` from HTTP / DB | Return it; it's usually correct |
+| `time.Sleep` in request handlers | Use `time.After` inside `select` with `ctx.Done()` |
+| Mixing `errgroup` and your own waitgroup | Pick one |

package/skills/golang/references/errors.md

@@ -0,0 +1,241 @@
+# Go — Errors
+
+`error` interface, wrapping, `errors.Is/As`, sentinel vs. typed errors. For general strategy, see `coding-standards/references/error-strategy.md`.
+
+## The `error` interface
+
+```go
+type error interface {
+    Error() string
+}
+```
+
+That's it. Any type with an `Error() string` method is an error.
+
+## Return errors; don't panic
+
+Go signals failure by returning an error as the last value. Callers must handle it.
+
+```go
+f, err := os.Open(path)
+if err != nil {
+    return fmt.Errorf("open %s: %w", path, err)
+}
+defer f.Close()
+```
+
+Panic only for:
+- Programmer errors (nil deref on a value you just constructed)
+- Unrecoverable state (corrupted global, failed init on a must-have resource)
+- `init()` failures
+
+Never panic across a library boundary. Recover at the edge if you must, and log.
+
+## Wrap with `%w`, not `%v` or `%s`
+
+`fmt.Errorf` with `%w` preserves the underlying error for `errors.Is` / `errors.As`.
+
+```go
+// ✅
+return fmt.Errorf("load config %q: %w", path, err)
+
+// ❌ loses the original
+return fmt.Errorf("load config %q: %v", path, err)
+```
+
+Wrap at each layer you cross. The final error has a breadcrumb trail.
+
+```
+load config "/etc/app.yaml": parse yaml: invalid syntax at line 12
+```
+
+## `errors.Is` — sentinel comparison
+
+For "fixed" errors that the caller wants to match.
+
+```go
+var ErrNotFound = errors.New("not found")
+
+func Find(id string) (*User, error) {
+    if ... { return nil, ErrNotFound }
+    ...
+}
+
+// Caller
+u, err := Find(id)
+if errors.Is(err, ErrNotFound) {
+    return http.StatusNotFound, nil
+}
+```
+
+`errors.Is` walks the wrap chain. Direct `==` comparison does not — use `errors.Is`.
+
+## `errors.As` — typed errors with fields
+
+When the caller needs data from the error (status code, field name), use a type with `errors.As`.
+
+```go
+type ValidationError struct {
+    Field   string
+    Message string
+}
+
+func (e *ValidationError) Error() string {
+    return fmt.Sprintf("%s: %s", e.Field, e.Message)
+}
+
+// Caller
+var ve *ValidationError
+if errors.As(err, &ve) {
+    return fmt.Sprintf("field %s invalid", ve.Field)
+}
+```
+
+`errors.As` walks the chain and binds to the first matching type.
+
+## Sentinel vs. typed — when to use which
+
+| Use a sentinel (`var ErrX = errors.New(...)`) | Use a typed error |
+|---|---|
+| Caller only needs to know "is it X?" | Caller needs details (field, code, retry-after) |
+| Common across packages: `io.EOF`, `sql.ErrNoRows` | Validation failures, HTTP errors, domain errors |
+| One concept, one value | Data varies per occurrence |
+
+Prefer typed errors for anything the caller acts on with specific logic.
+
+## Where to define errors
+
+- **Sentinels**: in the package that can produce them. `package user`: `var ErrUserNotFound = errors.New("user not found")`.
+- **Types**: same rule. Domain errors live in the domain package.
+
+Don't put all errors in a shared `errors` package — it couples everything.
+
+## Don't discard context
+
+```go
+// ❌ loses the cause
+if err != nil {
+    return errors.New("something failed")
+}
+
+// ❌ loses the cause and the stack
+if err != nil {
+    log.Println("error:", err)
+    return nil
+}
+
+// ✅
+if err != nil {
+    return fmt.Errorf("load user %s: %w", id, err)
+}
+```
+
+A wrapped error is dozens of times cheaper to debug than an unwrapped one.
+
+## Check errors once, at the right place
+
+```go
+// ❌ stutter — log + rewrap + return
+if err != nil {
+    log.Printf("load failed: %v", err)
+    return fmt.Errorf("load: %w", err)
+}
+
+// ✅ let the caller decide
+if err != nil {
+    return fmt.Errorf("load %s: %w", id, err)
+}
+```
+
+Log where the error is **handled** (not re-thrown). Every rethrow-then-log doubles log volume.
+
+## Edge: translate errors to HTTP status
+
+```go
+func writeError(w http.ResponseWriter, err error) {
+    var ve *ValidationError
+    switch {
+    case errors.As(err, &ve):
+        http.Error(w, ve.Error(), http.StatusUnprocessableEntity)
+    case errors.Is(err, ErrNotFound):
+        http.Error(w, "not found", http.StatusNotFound)
+    case errors.Is(err, ErrUnauthorized):
+        http.Error(w, "unauthorized", http.StatusUnauthorized)
+    default:
+        log.Printf("internal: %v", err)
+        http.Error(w, "internal error", http.StatusInternalServerError)
+    }
+}
+```
+
+One translator, at the edge. Handlers just return errors.
+
+## `errors.Join` — multiple errors at once
+
+Go 1.20+: collect errors from a batch.
+
+```go
+var errs []error
+for _, x := range xs {
+    if err := process(x); err != nil {
+        errs = append(errs, err)
+    }
+}
+if err := errors.Join(errs...); err != nil {
+    return err
+}
+```
+
+`errors.Is` / `errors.As` work across joined errors.
+
+## `defer` + named returns for cleanup errors
+
+When `Close` can fail and you want to surface it:
+
+```go
+func write(path string, data []byte) (err error) {
+    f, err := os.Create(path)
+    if err != nil { return err }
+    defer func() {
+        if cerr := f.Close(); cerr != nil && err == nil {
+            err = cerr
+        }
+    }()
+    _, err = f.Write(data)
+    return err
+}
+```
+
+Named return `err` is read by the deferred func. Use sparingly — only when the cleanup error matters.
+
+## `panic` / `recover` — edge cases only
+
+```go
+// One legitimate use: HTTP middleware recovering a goroutine panic
+func recoverMW(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        defer func() {
+            if rv := recover(); rv != nil {
+                log.Printf("panic: %v\n%s", rv, debug.Stack())
+                http.Error(w, "internal error", http.StatusInternalServerError)
+            }
+        }()
+        next.ServeHTTP(w, r)
+    })
+}
+```
+
+Everywhere else: return `error`. `recover` is a safety net, not a control-flow tool.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `if err != nil { return err }` with no context | Wrap: `fmt.Errorf("op: %w", err)` |
+| `errors.New("failed")` at every layer — no detail | Include the inputs and the operation |
+| Returning `nil` error but also `nil` result | Decide the contract; don't force callers to guess |
+| `recover` to "keep the server running" through bugs | Fix the bug; panics are bugs |
+| String comparison on error messages | `errors.Is` / `errors.As` |
+| Single huge `Error` struct with a `.Code` field | Use typed errors + `errors.As` |
+| `log.Fatal` / `os.Exit` from deep inside libraries | Return; let `main` decide |
+| `_ = someErrorReturningCall()` without a comment | Either handle or document the reason |