oh-my-customcodex 0.1.0

package/templates/guides/go-backend/project-layout.md

@@ -0,0 +1,243 @@
+# Standard Go Project Layout
+
+> Source: https://github.com/golang-standards/project-layout
+
+## Directory Structure
+
+```
+project/
+├── cmd/                    # Main applications
+│   ├── server/
+│   │   └── main.go
+│   └── worker/
+│       └── main.go
+├── internal/               # Private code
+│   ├── handler/
+│   ├── service/
+│   ├── repository/
+│   ├── model/
+│   └── config/
+├── pkg/                    # Public library code
+│   └── validator/
+├── api/                    # API definitions
+│   ├── openapi.yaml
+│   └── proto/
+├── configs/                # Configuration files
+│   └── config.yaml
+├── scripts/                # Build scripts
+│   └── build.sh
+├── test/                   # Additional test data
+│   └── testdata/
+├── docs/                   # Documentation
+├── Dockerfile
+├── Makefile
+├── go.mod
+└── go.sum
+```
+
+## Directory Descriptions
+
+### `/cmd`
+
+Main applications for this project. Each application has its own subdirectory.
+
+```go
+// cmd/server/main.go
+package main
+
+import (
+    "log"
+    "myapp/internal/config"
+    "myapp/internal/handler"
+    "myapp/internal/service"
+)
+
+func main() {
+    cfg, err := config.Load()
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    svc := service.New(cfg)
+    h := handler.New(svc)
+
+    log.Fatal(h.ListenAndServe(cfg.Addr))
+}
+```
+
+### `/internal`
+
+Private application and library code. Not importable by other projects.
+
+```
+internal/
+├── handler/        # HTTP/gRPC handlers
+│   └── user.go
+├── service/        # Business logic
+│   └── user.go
+├── repository/     # Data access
+│   └── user.go
+├── model/          # Domain models
+│   └── user.go
+└── config/         # Configuration
+    └── config.go
+```
+
+### `/pkg`
+
+Library code safe for external use.
+
+```go
+// pkg/validator/validator.go
+package validator
+
+func ValidateEmail(email string) bool {
+    // validation logic
+}
+```
+
+### `/api`
+
+API definitions (OpenAPI/Swagger, Protocol Buffers).
+
+```yaml
+# api/openapi.yaml
+openapi: "3.0.0"
+info:
+  title: "My API"
+  version: "1.0.0"
+paths:
+  /users:
+    get:
+      summary: "List users"
+```
+
+## Common Patterns
+
+### Application Structure
+
+```go
+// internal/app/app.go
+type App struct {
+    config  *config.Config
+    db      *sql.DB
+    cache   *redis.Client
+    handler *handler.Handler
+}
+
+func New(cfg *config.Config) (*App, error) {
+    db, err := sql.Open("postgres", cfg.DatabaseURL)
+    if err != nil {
+        return nil, fmt.Errorf("open db: %w", err)
+    }
+
+    cache := redis.NewClient(&redis.Options{
+        Addr: cfg.RedisURL,
+    })
+
+    repo := repository.New(db)
+    svc := service.New(repo, cache)
+    h := handler.New(svc)
+
+    return &App{
+        config:  cfg,
+        db:      db,
+        cache:   cache,
+        handler: h,
+    }, nil
+}
+
+func (a *App) Run() error {
+    return http.ListenAndServe(a.config.Addr, a.handler.Router())
+}
+
+func (a *App) Shutdown(ctx context.Context) error {
+    if err := a.db.Close(); err != nil {
+        return err
+    }
+    return a.cache.Close()
+}
+```
+
+### Main Entry Point
+
+```go
+// cmd/server/main.go
+package main
+
+import (
+    "context"
+    "log/slog"
+    "os"
+    "os/signal"
+    "syscall"
+
+    "myapp/internal/app"
+    "myapp/internal/config"
+)
+
+func main() {
+    logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+    slog.SetDefault(logger)
+
+    cfg, err := config.Load()
+    if err != nil {
+        slog.Error("load config", "error", err)
+        os.Exit(1)
+    }
+
+    application, err := app.New(cfg)
+    if err != nil {
+        slog.Error("create app", "error", err)
+        os.Exit(1)
+    }
+
+    // Graceful shutdown
+    ctx, stop := signal.NotifyContext(
+        context.Background(),
+        syscall.SIGINT, syscall.SIGTERM,
+    )
+    defer stop()
+
+    go func() {
+        slog.Info("starting server", "addr", cfg.Addr)
+        if err := application.Run(); err != nil {
+            slog.Error("server error", "error", err)
+        }
+    }()
+
+    <-ctx.Done()
+    slog.Info("shutting down")
+
+    shutdownCtx, cancel := context.WithTimeout(
+        context.Background(),
+        30*time.Second,
+    )
+    defer cancel()
+
+    if err := application.Shutdown(shutdownCtx); err != nil {
+        slog.Error("shutdown error", "error", err)
+    }
+}
+```
+
+### Makefile
+
+```makefile
+.PHONY: build run test lint
+
+build:
+	go build -o bin/server ./cmd/server
+
+run:
+	go run ./cmd/server
+
+test:
+	go test -v -race ./...
+
+lint:
+	golangci-lint run
+
+docker:
+	docker build -t myapp .
+```

package/templates/guides/go-backend/uber-style.md

@@ -0,0 +1,212 @@
+# Uber Go Style Guide
+
+> Source: https://github.com/uber-go/guide/blob/master/style.md
+
+## Guidelines
+
+### Verify Interface Compliance
+
+```go
+// Compile-time check
+var _ http.Handler = (*Handler)(nil)
+var _ io.Reader = (*MyReader)(nil)
+```
+
+### Receiver Type
+
+```go
+// Value receiver: doesn't modify state
+func (s Stack) Length() int {
+    return len(s.items)
+}
+
+// Pointer receiver: modifies state or is large
+func (s *Stack) Push(item int) {
+    s.items = append(s.items, item)
+}
+```
+
+### Zero-value Mutexes
+
+```go
+// Good: zero-value is valid
+var mu sync.Mutex
+
+// Good: embedded in struct
+type Store struct {
+    mu    sync.Mutex
+    items map[string]Item
+}
+```
+
+### Copy Slices and Maps
+
+```go
+// Returning: copy to prevent external modification
+func (s *Store) GetItems() []Item {
+    s.mu.RLock()
+    defer s.mu.RUnlock()
+    items := make([]Item, len(s.items))
+    copy(items, s.items)
+    return items
+}
+
+// Receiving: copy to prevent caller modification
+func (s *Store) SetItems(items []Item) {
+    s.mu.Lock()
+    defer s.mu.Unlock()
+    s.items = make([]Item, len(items))
+    copy(s.items, items)
+}
+```
+
+### Defer for Cleanup
+
+```go
+func readFile(path string) ([]byte, error) {
+    f, err := os.Open(path)
+    if err != nil {
+        return nil, err
+    }
+    defer f.Close()
+    return io.ReadAll(f)
+}
+
+func process() {
+    mu.Lock()
+    defer mu.Unlock()
+    // ...
+}
+```
+
+### Channel Size
+
+```go
+// Good: unbuffered or 1
+ch := make(chan int)
+ch := make(chan int, 1)
+
+// Requires justification
+ch := make(chan int, 100) // Why 100?
+```
+
+### Start Enums at One
+
+```go
+type Operation int
+
+const (
+    Add Operation = iota + 1
+    Subtract
+    Multiply
+)
+```
+
+### Error Types
+
+```go
+// Sentinel errors
+var ErrNotFound = errors.New("not found")
+
+// Error wrapping
+if err != nil {
+    return fmt.Errorf("failed to get user: %w", err)
+}
+
+// Checking errors
+if errors.Is(err, ErrNotFound) {
+    // handle not found
+}
+```
+
+### Handle Errors Once
+
+```go
+// Bad: logs AND returns
+if err != nil {
+    log.Printf("error: %v", err)
+    return err
+}
+
+// Good: return with context
+if err != nil {
+    return fmt.Errorf("process: %w", err)
+}
+```
+
+### Use strconv Over fmt
+
+```go
+// Good
+s := strconv.Itoa(n)
+n, err := strconv.Atoi(s)
+
+// Slower
+s := fmt.Sprintf("%d", n)
+```
+
+### Table-Driven Tests
+
+```go
+func TestSplit(t *testing.T) {
+    tests := []struct {
+        name  string
+        input string
+        sep   string
+        want  []string
+    }{
+        {
+            name:  "simple",
+            input: "a/b/c",
+            sep:   "/",
+            want:  []string{"a", "b", "c"},
+        },
+        {
+            name:  "empty",
+            input: "",
+            sep:   "/",
+            want:  []string{""},
+        },
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            got := strings.Split(tt.input, tt.sep)
+            if diff := cmp.Diff(tt.want, got); diff != "" {
+                t.Errorf("mismatch (-want +got):\n%s", diff)
+            }
+        })
+    }
+}
+```
+
+### Functional Options
+
+```go
+type Server struct {
+    addr    string
+    timeout time.Duration
+}
+
+type Option func(*Server)
+
+func WithTimeout(d time.Duration) Option {
+    return func(s *Server) {
+        s.timeout = d
+    }
+}
+
+func NewServer(addr string, opts ...Option) *Server {
+    s := &Server{
+        addr:    addr,
+        timeout: time.Second * 30,
+    }
+    for _, opt := range opts {
+        opt(s)
+    }
+    return s
+}
+
+// Usage
+server := NewServer(":8080", WithTimeout(time.Minute))
+```

package/templates/guides/golang/concurrency.md

@@ -0,0 +1,282 @@
+# Go Concurrency Patterns
+
+> Reference for concurrent programming in Go
+
+## Core Philosophy
+
+> Do not communicate by sharing memory; instead, share memory by communicating.
+
+Go's approach to concurrency differs from traditional threading models. Channels provide a way to safely communicate between goroutines without explicit locks.
+
+## Goroutines
+
+A goroutine is a lightweight thread managed by the Go runtime.
+
+```go
+// Start a goroutine
+go doSomething()
+
+// With anonymous function
+go func() {
+    // concurrent work
+}()
+```
+
+### Goroutine Lifecycle
+
+- Created with `go` keyword
+- Runs concurrently with calling goroutine
+- Exits when function returns
+- Main goroutine exit = program exit
+
+## Channels
+
+### Basic Operations
+
+```go
+// Create
+ch := make(chan int)        // unbuffered
+ch := make(chan int, 10)    // buffered, capacity 10
+
+// Send
+ch <- value
+
+// Receive
+value := <-ch
+value, ok := <-ch  // ok is false if channel closed
+
+// Close
+close(ch)
+```
+
+### Unbuffered vs Buffered
+
+| Type | Behavior |
+|------|----------|
+| Unbuffered | Sender blocks until receiver ready |
+| Buffered | Sender blocks only when buffer full |
+
+### Directional Channels
+
+```go
+func sender(ch chan<- int) {
+    ch <- 42  // send-only
+}
+
+func receiver(ch <-chan int) {
+    v := <-ch  // receive-only
+}
+```
+
+## Common Patterns
+
+### Worker Pool
+
+```go
+func worker(id int, jobs <-chan int, results chan<- int) {
+    for j := range jobs {
+        results <- j * 2
+    }
+}
+
+func main() {
+    jobs := make(chan int, 100)
+    results := make(chan int, 100)
+
+    // Start 3 workers
+    for w := 1; w <= 3; w++ {
+        go worker(w, jobs, results)
+    }
+
+    // Send jobs
+    for j := 1; j <= 9; j++ {
+        jobs <- j
+    }
+    close(jobs)
+
+    // Collect results
+    for a := 1; a <= 9; a++ {
+        <-results
+    }
+}
+```
+
+### Fan-Out, Fan-In
+
+```go
+// Fan-out: multiple goroutines read from same channel
+// Fan-in: single goroutine reads from multiple channels
+
+func fanIn(ch1, ch2 <-chan int) <-chan int {
+    out := make(chan int)
+    go func() {
+        for {
+            select {
+            case v := <-ch1:
+                out <- v
+            case v := <-ch2:
+                out <- v
+            }
+        }
+    }()
+    return out
+}
+```
+
+### Pipeline
+
+```go
+func gen(nums ...int) <-chan int {
+    out := make(chan int)
+    go func() {
+        for _, n := range nums {
+            out <- n
+        }
+        close(out)
+    }()
+    return out
+}
+
+func sq(in <-chan int) <-chan int {
+    out := make(chan int)
+    go func() {
+        for n := range in {
+            out <- n * n
+        }
+        close(out)
+    }()
+    return out
+}
+
+// Usage: for v := range sq(sq(gen(2, 3))) { ... }
+```
+
+### Context for Cancellation
+
+```go
+func operation(ctx context.Context) error {
+    select {
+    case <-time.After(time.Second):
+        return nil  // completed
+    case <-ctx.Done():
+        return ctx.Err()  // cancelled
+    }
+}
+
+func main() {
+    ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
+    defer cancel()
+
+    if err := operation(ctx); err != nil {
+        log.Fatal(err)
+    }
+}
+```
+
+## Select Statement
+
+```go
+select {
+case v := <-ch1:
+    // received from ch1
+case ch2 <- x:
+    // sent to ch2
+case <-time.After(time.Second):
+    // timeout
+default:
+    // non-blocking
+}
+```
+
+## Synchronization
+
+### sync.WaitGroup
+
+```go
+var wg sync.WaitGroup
+
+for i := 0; i < 5; i++ {
+    wg.Add(1)
+    go func(id int) {
+        defer wg.Done()
+        // work
+    }(i)
+}
+
+wg.Wait()  // blocks until all done
+```
+
+### sync.Mutex
+
+```go
+var (
+    mu      sync.Mutex
+    counter int
+)
+
+func increment() {
+    mu.Lock()
+    defer mu.Unlock()
+    counter++
+}
+```
+
+### sync.Once
+
+```go
+var once sync.Once
+
+func initialize() {
+    once.Do(func() {
+        // runs exactly once
+    })
+}
+```
+
+## Avoiding Common Pitfalls
+
+### Goroutine Leaks
+
+```go
+// BAD: goroutine never exits
+go func() {
+    for {
+        // infinite loop with no exit
+    }
+}()
+
+// GOOD: use context or done channel
+go func(ctx context.Context) {
+    for {
+        select {
+        case <-ctx.Done():
+            return
+        default:
+            // work
+        }
+    }
+}(ctx)
+```
+
+### Race Conditions
+
+```go
+// BAD: race condition
+go func() { x++ }()
+go func() { x++ }()
+
+// GOOD: use channels or mutex
+go func() { ch <- 1 }()
+go func() { ch <- 1 }()
+x += <-ch + <-ch
+```
+
+### Closing Channels
+
+```go
+// Only sender should close
+// Closing already-closed channel panics
+// Sending to closed channel panics
+
+// Pattern: use sync.Once or single sender
+```