codehava-agent-kit 1.0.1 → 3.0.0

package/templates/.agent/skills/go-concurrency-patterns/resources/implementation-playbook.md

@@ -0,0 +1,654 @@
+# Go Concurrency Patterns Implementation Playbook
+
+This file contains detailed patterns, checklists, and code samples referenced by the skill.
+
+# Go Concurrency Patterns
+
+Production patterns for Go concurrency including goroutines, channels, synchronization primitives, and context management.
+
+## When to Use This Skill
+
+- Building concurrent Go applications
+- Implementing worker pools and pipelines
+- Managing goroutine lifecycles
+- Using channels for communication
+- Debugging race conditions
+- Implementing graceful shutdown
+
+## Core Concepts
+
+### 1. Go Concurrency Primitives
+
+| Primitive | Purpose |
+|-----------|---------|
+| `goroutine` | Lightweight concurrent execution |
+| `channel` | Communication between goroutines |
+| `select` | Multiplex channel operations |
+| `sync.Mutex` | Mutual exclusion |
+| `sync.WaitGroup` | Wait for goroutines to complete |
+| `context.Context` | Cancellation and deadlines |
+
+### 2. Go Concurrency Mantra
+
+```
+Don't communicate by sharing memory;
+share memory by communicating.
+```
+
+## Quick Start
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "sync"
+    "time"
+)
+
+func main() {
+    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+    defer cancel()
+
+    results := make(chan string, 10)
+    var wg sync.WaitGroup
+
+    // Spawn workers
+    for i := 0; i < 3; i++ {
+        wg.Add(1)
+        go worker(ctx, i, results, &wg)
+    }
+
+    // Close results when done
+    go func() {
+        wg.Wait()
+        close(results)
+    }()
+
+    // Collect results
+    for result := range results {
+        fmt.Println(result)
+    }
+}
+
+func worker(ctx context.Context, id int, results chan<- string, wg *sync.WaitGroup) {
+    defer wg.Done()
+
+    select {
+    case <-ctx.Done():
+        return
+    case results <- fmt.Sprintf("Worker %d done", id):
+    }
+}
+```
+
+## Patterns
+
+### Pattern 1: Worker Pool
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "sync"
+)
+
+type Job struct {
+    ID   int
+    Data string
+}
+
+type Result struct {
+    JobID int
+    Output string
+    Err   error
+}
+
+func WorkerPool(ctx context.Context, numWorkers int, jobs <-chan Job) <-chan Result {
+    results := make(chan Result, len(jobs))
+
+    var wg sync.WaitGroup
+    for i := 0; i < numWorkers; i++ {
+        wg.Add(1)
+        go func(workerID int) {
+            defer wg.Done()
+            for job := range jobs {
+                select {
+                case <-ctx.Done():
+                    return
+                default:
+                    result := processJob(job)
+                    results <- result
+                }
+            }
+        }(i)
+    }
+
+    go func() {
+        wg.Wait()
+        close(results)
+    }()
+
+    return results
+}
+
+func processJob(job Job) Result {
+    // Simulate work
+    return Result{
+        JobID:  job.ID,
+        Output: fmt.Sprintf("Processed: %s", job.Data),
+    }
+}
+
+// Usage
+func main() {
+    ctx, cancel := context.WithCancel(context.Background())
+    defer cancel()
+
+    jobs := make(chan Job, 100)
+
+    // Send jobs
+    go func() {
+        for i := 0; i < 50; i++ {
+            jobs <- Job{ID: i, Data: fmt.Sprintf("job-%d", i)}
+        }
+        close(jobs)
+    }()
+
+    // Process with 5 workers
+    results := WorkerPool(ctx, 5, jobs)
+
+    for result := range results {
+        fmt.Printf("Result: %+v\n", result)
+    }
+}
+```
+
+### Pattern 2: Fan-Out/Fan-In Pipeline
+
+```go
+package main
+
+import (
+    "context"
+    "sync"
+)
+
+// Stage 1: Generate numbers
+func generate(ctx context.Context, nums ...int) <-chan int {
+    out := make(chan int)
+    go func() {
+        defer close(out)
+        for _, n := range nums {
+            select {
+            case <-ctx.Done():
+                return
+            case out <- n:
+            }
+        }
+    }()
+    return out
+}
+
+// Stage 2: Square numbers (can run multiple instances)
+func square(ctx context.Context, in <-chan int) <-chan int {
+    out := make(chan int)
+    go func() {
+        defer close(out)
+        for n := range in {
+            select {
+            case <-ctx.Done():
+                return
+            case out <- n * n:
+            }
+        }
+    }()
+    return out
+}
+
+// Fan-in: Merge multiple channels into one
+func merge(ctx context.Context, cs ...<-chan int) <-chan int {
+    var wg sync.WaitGroup
+    out := make(chan int)
+
+    // Start output goroutine for each input channel
+    output := func(c <-chan int) {
+        defer wg.Done()
+        for n := range c {
+            select {
+            case <-ctx.Done():
+                return
+            case out <- n:
+            }
+        }
+    }
+
+    wg.Add(len(cs))
+    for _, c := range cs {
+        go output(c)
+    }
+
+    // Close out after all inputs are done
+    go func() {
+        wg.Wait()
+        close(out)
+    }()
+
+    return out
+}
+
+func main() {
+    ctx, cancel := context.WithCancel(context.Background())
+    defer cancel()
+
+    // Generate input
+    in := generate(ctx, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
+
+    // Fan out to multiple squarers
+    c1 := square(ctx, in)
+    c2 := square(ctx, in)
+    c3 := square(ctx, in)
+
+    // Fan in results
+    for result := range merge(ctx, c1, c2, c3) {
+        fmt.Println(result)
+    }
+}
+```
+
+### Pattern 3: Bounded Concurrency with Semaphore
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "golang.org/x/sync/semaphore"
+    "sync"
+)
+
+type RateLimitedWorker struct {
+    sem *semaphore.Weighted
+}
+
+func NewRateLimitedWorker(maxConcurrent int64) *RateLimitedWorker {
+    return &RateLimitedWorker{
+        sem: semaphore.NewWeighted(maxConcurrent),
+    }
+}
+
+func (w *RateLimitedWorker) Do(ctx context.Context, tasks []func() error) []error {
+    var (
+        wg     sync.WaitGroup
+        mu     sync.Mutex
+        errors []error
+    )
+
+    for _, task := range tasks {
+        // Acquire semaphore (blocks if at limit)
+        if err := w.sem.Acquire(ctx, 1); err != nil {
+            return []error{err}
+        }
+
+        wg.Add(1)
+        go func(t func() error) {
+            defer wg.Done()
+            defer w.sem.Release(1)
+
+            if err := t(); err != nil {
+                mu.Lock()
+                errors = append(errors, err)
+                mu.Unlock()
+            }
+        }(task)
+    }
+
+    wg.Wait()
+    return errors
+}
+
+// Alternative: Channel-based semaphore
+type Semaphore chan struct{}
+
+func NewSemaphore(n int) Semaphore {
+    return make(chan struct{}, n)
+}
+
+func (s Semaphore) Acquire() {
+    s <- struct{}{}
+}
+
+func (s Semaphore) Release() {
+    <-s
+}
+```
+
+### Pattern 4: Graceful Shutdown
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "os"
+    "os/signal"
+    "sync"
+    "syscall"
+    "time"
+)
+
+type Server struct {
+    shutdown chan struct{}
+    wg       sync.WaitGroup
+}
+
+func NewServer() *Server {
+    return &Server{
+        shutdown: make(chan struct{}),
+    }
+}
+
+func (s *Server) Start(ctx context.Context) {
+    // Start workers
+    for i := 0; i < 5; i++ {
+        s.wg.Add(1)
+        go s.worker(ctx, i)
+    }
+}
+
+func (s *Server) worker(ctx context.Context, id int) {
+    defer s.wg.Done()
+    defer fmt.Printf("Worker %d stopped\n", id)
+
+    ticker := time.NewTicker(time.Second)
+    defer ticker.Stop()
+
+    for {
+        select {
+        case <-ctx.Done():
+            // Cleanup
+            fmt.Printf("Worker %d cleaning up...\n", id)
+            time.Sleep(500 * time.Millisecond) // Simulated cleanup
+            return
+        case <-ticker.C:
+            fmt.Printf("Worker %d working...\n", id)
+        }
+    }
+}
+
+func (s *Server) Shutdown(timeout time.Duration) {
+    // Signal shutdown
+    close(s.shutdown)
+
+    // Wait with timeout
+    done := make(chan struct{})
+    go func() {
+        s.wg.Wait()
+        close(done)
+    }()
+
+    select {
+    case <-done:
+        fmt.Println("Clean shutdown completed")
+    case <-time.After(timeout):
+        fmt.Println("Shutdown timed out, forcing exit")
+    }
+}
+
+func main() {
+    // Setup signal handling
+    ctx, cancel := context.WithCancel(context.Background())
+
+    sigCh := make(chan os.Signal, 1)
+    signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
+
+    server := NewServer()
+    server.Start(ctx)
+
+    // Wait for signal
+    sig := <-sigCh
+    fmt.Printf("\nReceived signal: %v\n", sig)
+
+    // Cancel context to stop workers
+    cancel()
+
+    // Wait for graceful shutdown
+    server.Shutdown(5 * time.Second)
+}
+```
+
+### Pattern 5: Error Group with Cancellation
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "golang.org/x/sync/errgroup"
+    "net/http"
+)
+
+func fetchAllURLs(ctx context.Context, urls []string) ([]string, error) {
+    g, ctx := errgroup.WithContext(ctx)
+
+    results := make([]string, len(urls))
+
+    for i, url := range urls {
+        i, url := i, url // Capture loop variables
+
+        g.Go(func() error {
+            req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
+            if err != nil {
+                return fmt.Errorf("creating request for %s: %w", url, err)
+            }
+
+            resp, err := http.DefaultClient.Do(req)
+            if err != nil {
+                return fmt.Errorf("fetching %s: %w", url, err)
+            }
+            defer resp.Body.Close()
+
+            results[i] = fmt.Sprintf("%s: %d", url, resp.StatusCode)
+            return nil
+        })
+    }
+
+    // Wait for all goroutines to complete or one to fail
+    if err := g.Wait(); err != nil {
+        return nil, err // First error cancels all others
+    }
+
+    return results, nil
+}
+
+// With concurrency limit
+func fetchWithLimit(ctx context.Context, urls []string, limit int) ([]string, error) {
+    g, ctx := errgroup.WithContext(ctx)
+    g.SetLimit(limit) // Max concurrent goroutines
+
+    results := make([]string, len(urls))
+    var mu sync.Mutex
+
+    for i, url := range urls {
+        i, url := i, url
+
+        g.Go(func() error {
+            result, err := fetchURL(ctx, url)
+            if err != nil {
+                return err
+            }
+
+            mu.Lock()
+            results[i] = result
+            mu.Unlock()
+            return nil
+        })
+    }
+
+    if err := g.Wait(); err != nil {
+        return nil, err
+    }
+
+    return results, nil
+}
+```
+
+### Pattern 6: Concurrent Map with sync.Map
+
+```go
+package main
+
+import (
+    "sync"
+)
+
+// For frequent reads, infrequent writes
+type Cache struct {
+    m sync.Map
+}
+
+func (c *Cache) Get(key string) (interface{}, bool) {
+    return c.m.Load(key)
+}
+
+func (c *Cache) Set(key string, value interface{}) {
+    c.m.Store(key, value)
+}
+
+func (c *Cache) GetOrSet(key string, value interface{}) (interface{}, bool) {
+    return c.m.LoadOrStore(key, value)
+}
+
+func (c *Cache) Delete(key string) {
+    c.m.Delete(key)
+}
+
+// For write-heavy workloads, use sharded map
+type ShardedMap struct {
+    shards    []*shard
+    numShards int
+}
+
+type shard struct {
+    sync.RWMutex
+    data map[string]interface{}
+}
+
+func NewShardedMap(numShards int) *ShardedMap {
+    m := &ShardedMap{
+        shards:    make([]*shard, numShards),
+        numShards: numShards,
+    }
+    for i := range m.shards {
+        m.shards[i] = &shard{data: make(map[string]interface{})}
+    }
+    return m
+}
+
+func (m *ShardedMap) getShard(key string) *shard {
+    // Simple hash
+    h := 0
+    for _, c := range key {
+        h = 31*h + int(c)
+    }
+    return m.shards[h%m.numShards]
+}
+
+func (m *ShardedMap) Get(key string) (interface{}, bool) {
+    shard := m.getShard(key)
+    shard.RLock()
+    defer shard.RUnlock()
+    v, ok := shard.data[key]
+    return v, ok
+}
+
+func (m *ShardedMap) Set(key string, value interface{}) {
+    shard := m.getShard(key)
+    shard.Lock()
+    defer shard.Unlock()
+    shard.data[key] = value
+}
+```
+
+### Pattern 7: Select with Timeout and Default
+
+```go
+func selectPatterns() {
+    ch := make(chan int)
+
+    // Timeout pattern
+    select {
+    case v := <-ch:
+        fmt.Println("Received:", v)
+    case <-time.After(time.Second):
+        fmt.Println("Timeout!")
+    }
+
+    // Non-blocking send/receive
+    select {
+    case ch <- 42:
+        fmt.Println("Sent")
+    default:
+        fmt.Println("Channel full, skipping")
+    }
+
+    // Priority select (check high priority first)
+    highPriority := make(chan int)
+    lowPriority := make(chan int)
+
+    for {
+        select {
+        case msg := <-highPriority:
+            fmt.Println("High priority:", msg)
+        default:
+            select {
+            case msg := <-highPriority:
+                fmt.Println("High priority:", msg)
+            case msg := <-lowPriority:
+                fmt.Println("Low priority:", msg)
+            }
+        }
+    }
+}
+```
+
+## Race Detection
+
+```bash
+# Run tests with race detector
+go test -race ./...
+
+# Build with race detector
+go build -race .
+
+# Run with race detector
+go run -race main.go
+```
+
+## Best Practices
+
+### Do's
+- **Use context** - For cancellation and deadlines
+- **Close channels** - From sender side only
+- **Use errgroup** - For concurrent operations with errors
+- **Buffer channels** - When you know the count
+- **Prefer channels** - Over mutexes when possible
+
+### Don'ts
+- **Don't leak goroutines** - Always have exit path
+- **Don't close from receiver** - Causes panic
+- **Don't use shared memory** - Unless necessary
+- **Don't ignore context cancellation** - Check ctx.Done()
+- **Don't use time.Sleep for sync** - Use proper primitives
+
+## Resources
+
+- [Go Concurrency Patterns](https://go.dev/blog/pipelines)
+- [Effective Go - Concurrency](https://go.dev/doc/effective_go#concurrency)
+- [Go by Example - Goroutines](https://gobyexample.com/goroutines)

package/templates/.agent/skills/go-playwright/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: go-playwright
+description: "Expert capability for robust, stealthy, and efficient browser automation using Playwright Go."
+risk: safe
+source: "https://github.com/playwright-community/playwright-go"
+date_added: "2026-02-27"
+---
+
+# Playwright Go Automation Expert
+
+## Overview
+This skill provides a comprehensive framework for writing high-performance, production-grade browser automation scripts using `github.com/playwright-community/playwright-go`. It enforces architectural best practices (contexts over instances), robust error handling, structured logging (Zap), and advanced human-emulation techniques to bypass anti-bot systems.
+
+## When to Use This Skill
+- Use when the user asks to "scrape," "automate," or "test" a website using Go.
+- Use when the target site has complex dynamic content (SPA, React, Vue) requiring a real browser.
+- Use when the user mentions "stealth," "avoiding detection," "cloudflare," or "human-like" behavior.
+- Use when debugging existing Playwright scripts.
+
+## Safety & Risk
+**Risk Level: 🔵 Safe**
+
+- **Sandboxed Execution:** Browser contexts are isolated; they do not persist data to the host machine unless explicitly saved.
+- **Resource Management:** Designed to close browsers and contexts via `defer` to prevent memory leaks.
+- **No External State-Change:** Default behavior is read-only (scraping/testing) unless the script is explicitly designed to submit forms or modify data.
+
+## Limitations
+- **Environment Dependencies:** Requires Playwright drivers and browsers to be installed (`go run github.com/playwright-community/playwright-go/cmd/playwright@latest install --with-deps`).
+- **Resource Intensity:** Launching full browser instances (even headless) consumes significant RAM/CPU. Use single-browser/multi-context architecture.
+- **Bot Detection:** While this skill includes stealth techniques, extremely strict anti-bot systems (e.g., rigorous Cloudflare settings) may still detect automation.
+- **CAPTCHAs:** Does not include built-in CAPTCHA solving capabilities.
+
+## Strategic Implementation Guidelines
+
+### 1. Architecture: Contexts vs. Browsers
+**CRITICAL:** Never launch a new `Browser` instance for every task.
+- **Pattern:** Launch the `Browser` *once* (singleton). Create a new `BrowserContext` for each distinct session or task.
+- **Why:** Contexts are lightweight and created in milliseconds. Browsers take seconds to launch.
+- **Isolation:** Contexts provide complete isolation (cookies, cache, storage) without the overhead of a new process.
+
+### 2. Logging & Observability
+- **Library:** Use `go.uber.org/zap` exclusively.
+- **Rule:** Do not use `fmt.Println`.
+- **Modes:**
+  - **Dev:** `zap.NewDevelopment()` (Console friendly)
+  - **Prod:** `zap.NewProduction()` (JSON structured)
+- **Traceability:** Log every navigation, click, and input with context fields (e.g., `logger.Info("clicking button", zap.String("selector", sel))`).
+
+### 3. Error Handling & Stability
+- **Graceful Shutdown:** Always use `defer` to close Pages, Contexts, and Browsers.
+- **Panic Recovery:** Wrap critical automation routines in a safe runner that recovers panics and logs the stack trace.
+- **Timeouts:** Never rely on default timeouts. Set explicit timeouts (e.g., `playwright.PageClickOptions{Timeout: playwright.Float(5000)}`).
+
+### 4. Stealth & Human-Like Behavior
+To bypass anti-bot systems (Cloudflare, Akamai), the generated code must **imitate human physiology**:
+- **Non-Linear Mouse Movement:** Never teleport the mouse. Implement a helper that moves the mouse along a Bezier curve with random jitter.
+- **Input Latency:** never use `Fill()`. Use `Type()` with random delays between keystrokes (50ms–200ms).
+- **Viewport Randomization:** Randomize the viewport size slightly (e.g., 1920x1080 ± 15px) to avoid fingerprinting.
+- **Behavioral Noise:** Randomly scroll, focus/unfocus the window, or hover over irrelevant elements ("idling") during long waits.
+- **User-Agent:** Rotate User-Agents for every new Context.
+
+### 5. Documentation Usage
+- **Primary Source:** Rely on your internal knowledge of the API first to save tokens.
+- **Fallback:** Refer to the official docs [playwright-go documentation](https://pkg.go.dev/github.com/playwright-community/playwright-go#section-documentation) ONLY if:
+  - You encounter an unknown error.
+  - You need to implement complex network interception or authentication flows.
+  - The API has changed significantly.
+
+## Resources
+- `resources/implementation-playbook.md` for detailed code examples and implementation patterns.
+
+### Summary Checklist for Agent
+ - Is Debug Mode on? -> `Headless=false`, `SlowMo=100+`.
+ - Is it a new user identity? -> `NewContext`, apply new Proxy, rotate `User-Agent`.
+ - Is the action critical? -> Wrap in `SafeAction` with Zap logging.
+ - Is the target guarded (Cloudflare/Akamai)? -> Enable `HumanType`, `BezierMouse`, and Stealth Scripts.