@cubis/foundry 0.3.83 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/go-fiber/examples/01-rest-api-with-middleware.md

@@ -1,126 +0,0 @@
-# Example: REST API with Middleware Stack
-
-## Prompt
-
-> Build a Fiber v3 REST API for a bookmarks service with CRUD endpoints under /api/v1/bookmarks. Include recovery, request logging, JWT auth, and request validation. Use a custom error handler for consistent JSON errors.
-
-## Expected Output
-
-The skill should produce a complete Fiber application with the following structure:
-
-### Application Bootstrap
-
-```go
-package main
-
-import (
-    "log"
-    "os"
-    "os/signal"
-    "syscall"
-    "time"
-
-    "github.com/gofiber/fiber/v3"
-    "github.com/gofiber/fiber/v3/middleware/recover"
-    "github.com/gofiber/fiber/v3/middleware/requestid"
-)
-
-func main() {
-    app := fiber.New(fiber.Config{
-        ErrorHandler:  customErrorHandler,
-        ReadTimeout:   10 * time.Second,
-        WriteTimeout:  10 * time.Second,
-        IdleTimeout:   120 * time.Second,
-        BodyLimit:     1 * 1024 * 1024, // 1MB
-    })
-
-    // Middleware stack: recovery first, then request ID, then logging
-    app.Use(recover.New())
-    app.Use(requestid.New())
-    app.Use(loggerMiddleware)
-
-    // API group with auth
-    api := app.Group("/api/v1")
-    api.Use(jwtAuthMiddleware)
-
-    // Bookmark routes
-    api.Get("/bookmarks", listBookmarks)
-    api.Post("/bookmarks", createBookmark)
-    api.Get("/bookmarks/:id", getBookmark)
-    api.Put("/bookmarks/:id", updateBookmark)
-    api.Delete("/bookmarks/:id", deleteBookmark)
-
-    // Graceful shutdown
-    go func() {
-        sigCh := make(chan os.Signal, 1)
-        signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
-        <-sigCh
-        log.Println("Shutting down...")
-        _ = app.ShutdownWithTimeout(30 * time.Second)
-    }()
-
-    log.Fatal(app.Listen(":8080"))
-}
-```
-
-### Custom Error Handler
-
-```go
-func customErrorHandler(c fiber.Ctx, err error) error {
-    code := fiber.StatusInternalServerError
-    message := "Internal Server Error"
-
-    var fe *fiber.Error
-    if errors.As(err, &fe) {
-        code = fe.Code
-        message = fe.Message
-    }
-
-    var ve *ValidationError
-    if errors.As(err, &ve) {
-        code = fiber.StatusBadRequest
-        return c.Status(code).JSON(ErrorResponse{
-            Code:    "VALIDATION_ERROR",
-            Message: "Request validation failed",
-            Details: ve.Fields,
-        })
-    }
-
-    return c.Status(code).JSON(ErrorResponse{
-        Code:    "ERROR",
-        Message: message,
-    })
-}
-```
-
-### Handler with Validation
-
-```go
-type CreateBookmarkRequest struct {
-    URL   string `json:"url" validate:"required,url"`
-    Title string `json:"title" validate:"required,min=1,max=200"`
-    Tags  []string `json:"tags" validate:"max=10,dive,min=1,max=50"`
-}
-
-func createBookmark(c fiber.Ctx) error {
-    var req CreateBookmarkRequest
-    if err := c.BodyParser(&req); err != nil {
-        return fiber.NewError(fiber.StatusBadRequest, "Invalid request body")
-    }
-    if err := validate.Struct(&req); err != nil {
-        return newValidationError(err)
-    }
-
-    bookmark := bookmarkService.Create(c.UserContext(), req)
-    return c.Status(fiber.StatusCreated).JSON(bookmark)
-}
-```
-
-## Key Observations
-
-- The app config includes timeouts and body limits for production safety.
-- Recovery middleware is outermost to catch panics from all subsequent middleware.
-- Route group applies auth middleware only to API routes, not health checks.
-- Validation uses struct tags with a shared validator instance.
-- The error handler distinguishes between Fiber errors, validation errors, and unknown errors.
-- Graceful shutdown listens for OS signals in a separate goroutine.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/go-fiber/examples/02-websocket-broadcast.md

@@ -1,154 +0,0 @@
-# Example: WebSocket Broadcast Service
-
-## Prompt
-
-> Create a Fiber service with a REST endpoint that publishes messages and a WebSocket endpoint that broadcasts those messages to all connected clients in real time. Include connection lifecycle management and tests.
-
-## Expected Output
-
-The skill should produce a Fiber application with both HTTP and WebSocket transports:
-
-### Connection Hub
-
-```go
-package ws
-
-import (
-    "sync"
-
-    "github.com/gofiber/contrib/websocket"
-)
-
-type Hub struct {
-    mu      sync.RWMutex
-    clients map[*websocket.Conn]bool
-}
-
-func NewHub() *Hub {
-    return &Hub{
-        clients: make(map[*websocket.Conn]bool),
-    }
-}
-
-func (h *Hub) Register(conn *websocket.Conn) {
-    h.mu.Lock()
-    defer h.mu.Unlock()
-    h.clients[conn] = true
-}
-
-func (h *Hub) Unregister(conn *websocket.Conn) {
-    h.mu.Lock()
-    defer h.mu.Unlock()
-    delete(h.clients, conn)
-    conn.Close()
-}
-
-func (h *Hub) Broadcast(messageType int, data []byte) {
-    h.mu.RLock()
-    defer h.mu.RUnlock()
-    for conn := range h.clients {
-        if err := conn.WriteMessage(messageType, data); err != nil {
-            // Connection will be cleaned up on next read error
-            continue
-        }
-    }
-}
-```
-
-### WebSocket Handler with Lifecycle
-
-```go
-func wsHandler(hub *Hub) func(*websocket.Conn) {
-    return func(c *websocket.Conn) {
-        hub.Register(c)
-        defer hub.Unregister(c)
-
-        // Configure connection limits
-        c.SetReadLimit(4096)
-        c.SetReadDeadline(time.Now().Add(60 * time.Second))
-        c.SetPongHandler(func(string) error {
-            c.SetReadDeadline(time.Now().Add(60 * time.Second))
-            return nil
-        })
-
-        // Read loop -- keeps the connection alive and detects disconnects
-        for {
-            _, _, err := c.ReadMessage()
-            if err != nil {
-                break // Client disconnected or error
-            }
-        }
-    }
-}
-```
-
-### Route Registration
-
-```go
-func setupRoutes(app *fiber.App, hub *Hub) {
-    // Health check (no auth)
-    app.Get("/api/health", func(c fiber.Ctx) error {
-        return c.JSON(fiber.Map{"status": "ok"})
-    })
-
-    // Publish message via REST
-    app.Post("/api/messages", func(c fiber.Ctx) error {
-        var msg MessageRequest
-        if err := c.BodyParser(&msg); err != nil {
-            return fiber.NewError(fiber.StatusBadRequest, "Invalid body")
-        }
-        data, _ := json.Marshal(msg)
-        hub.Broadcast(websocket.TextMessage, data)
-        return c.Status(fiber.StatusAccepted).JSON(fiber.Map{"published": true})
-    })
-
-    // WebSocket upgrade check + handler
-    app.Use("/ws", func(c fiber.Ctx) error {
-        if websocket.IsWebSocketUpgrade(c) {
-            return c.Next()
-        }
-        return fiber.ErrUpgradeRequired
-    })
-    app.Get("/ws", websocket.New(wsHandler(hub)))
-}
-```
-
-### Tests
-
-```go
-func TestHealthEndpoint(t *testing.T) {
-    hub := ws.NewHub()
-    app := fiber.New()
-    setupRoutes(app, hub)
-
-    req := httptest.NewRequest("GET", "/api/health", nil)
-    resp, err := app.Test(req)
-    require.NoError(t, err)
-    assert.Equal(t, 200, resp.StatusCode)
-
-    var body map[string]string
-    json.NewDecoder(resp.Body).Decode(&body)
-    assert.Equal(t, "ok", body["status"])
-}
-
-func TestWebSocketUpgradeRejection(t *testing.T) {
-    hub := ws.NewHub()
-    app := fiber.New()
-    setupRoutes(app, hub)
-
-    // Non-WebSocket request to /ws should be rejected
-    req := httptest.NewRequest("GET", "/ws", nil)
-    resp, err := app.Test(req)
-    require.NoError(t, err)
-    assert.Equal(t, 426, resp.StatusCode) // Upgrade Required
-}
-```
-
-## Key Observations
-
-- The hub uses `sync.RWMutex` for concurrent safety -- reads (broadcast) do not block each other.
-- The WebSocket handler sets read limits and ping/pong deadlines for liveness.
-- Connection cleanup is deferred so it always runs on disconnect.
-- The upgrade middleware checks `IsWebSocketUpgrade` before allowing the connection.
-- REST and WebSocket coexist on the same Fiber app with shared state through the hub.
-- Tests verify both the REST path and the WebSocket upgrade rejection without needing a real WebSocket client.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/go-fiber/references/error-handling.md

@@ -1,245 +0,0 @@
-# Fiber v3 Error Handling
-
-## Custom ErrorHandler
-
-Fiber's `ErrorHandler` in the app config is the central place for all error formatting. Every error returned from a handler or middleware flows through this function.
-
-```go
-app := fiber.New(fiber.Config{
-    ErrorHandler: func(c fiber.Ctx, err error) error {
-        code := fiber.StatusInternalServerError
-        response := ErrorResponse{
-            Code:    "INTERNAL_ERROR",
-            Message: "An unexpected error occurred",
-        }
-
-        // Handle Fiber errors (404, 405, etc.)
-        var fe *fiber.Error
-        if errors.As(err, &fe) {
-            code = fe.Code
-            response.Code = httpStatusToCode(fe.Code)
-            response.Message = fe.Message
-        }
-
-        // Handle validation errors
-        var ve *ValidationError
-        if errors.As(err, &ve) {
-            code = fiber.StatusBadRequest
-            response.Code = "VALIDATION_ERROR"
-            response.Message = "Request validation failed"
-            response.Details = ve.Fields
-        }
-
-        // Handle not-found errors
-        var nfe *NotFoundError
-        if errors.As(err, &nfe) {
-            code = fiber.StatusNotFound
-            response.Code = "NOT_FOUND"
-            response.Message = nfe.Error()
-        }
-
-        // Handle auth errors
-        var ae *AuthError
-        if errors.As(err, &ae) {
-            code = fiber.StatusUnauthorized
-            response.Code = ae.Code
-            response.Message = ae.Error()
-        }
-
-        // Log unexpected errors
-        if code == fiber.StatusInternalServerError {
-            log.Printf("ERROR: %v", err)
-        }
-
-        return c.Status(code).JSON(response)
-    },
-})
-```
-
-## Error Response Structure
-
-Define a consistent envelope for all error responses across the API.
-
-```go
-// ErrorResponse is the standard error envelope
-type ErrorResponse struct {
-    Code    string       `json:"code"`
-    Message string       `json:"message"`
-    Details []FieldError `json:"details,omitempty"`
-}
-
-// FieldError represents a single validation field error
-type FieldError struct {
-    Field   string `json:"field"`
-    Tag     string `json:"tag"`
-    Message string `json:"message"`
-}
-```
-
-## Custom Error Types
-
-Define domain-specific error types that carry enough context for the ErrorHandler to format them correctly.
-
-```go
-// ValidationError wraps validator.ValidationErrors with field details
-type ValidationError struct {
-    Fields []FieldError
-}
-
-func (e *ValidationError) Error() string {
-    return "validation failed"
-}
-
-func NewValidationError(err error) *ValidationError {
-    var ve validator.ValidationErrors
-    if !errors.As(err, &ve) {
-        return &ValidationError{
-            Fields: []FieldError{{Message: err.Error()}},
-        }
-    }
-
-    fields := make([]FieldError, len(ve))
-    for i, fe := range ve {
-        fields[i] = FieldError{
-            Field:   toSnakeCase(fe.Field()),
-            Tag:     fe.Tag(),
-            Message: formatFieldError(fe),
-        }
-    }
-    return &ValidationError{Fields: fields}
-}
-
-// NotFoundError for missing resources
-type NotFoundError struct {
-    Resource string
-    ID       string
-}
-
-func (e *NotFoundError) Error() string {
-    return fmt.Sprintf("%s with ID %s not found", e.Resource, e.ID)
-}
-
-// AuthError for authentication and authorization failures
-type AuthError struct {
-    Code    string
-    Reason  string
-}
-
-func (e *AuthError) Error() string {
-    return e.Reason
-}
-
-// ConflictError for duplicate resource creation
-type ConflictError struct {
-    Resource string
-    Field    string
-    Value    string
-}
-
-func (e *ConflictError) Error() string {
-    return fmt.Sprintf("%s with %s '%s' already exists", e.Resource, e.Field, e.Value)
-}
-```
-
-## Sentinel Errors
-
-Use sentinel errors for well-known conditions that handlers check with `errors.Is`.
-
-```go
-var (
-    ErrUnauthorized   = fiber.NewError(fiber.StatusUnauthorized, "Authentication required")
-    ErrForbidden      = fiber.NewError(fiber.StatusForbidden, "Insufficient permissions")
-    ErrNotFound       = fiber.NewError(fiber.StatusNotFound, "Resource not found")
-    ErrConflict       = fiber.NewError(fiber.StatusConflict, "Resource already exists")
-    ErrRateLimited    = fiber.NewError(fiber.StatusTooManyRequests, "Rate limit exceeded")
-    ErrServiceUnavail = fiber.NewError(fiber.StatusServiceUnavailable, "Service temporarily unavailable")
-)
-```
-
-## Using Errors in Handlers
-
-```go
-func getUser(c fiber.Ctx) error {
-    id := c.Params("id")
-    user, err := userService.FindByID(c.UserContext(), id)
-    if err != nil {
-        if errors.Is(err, sql.ErrNoRows) {
-            return &NotFoundError{Resource: "User", ID: id}
-        }
-        return err // Will be caught as 500 by ErrorHandler
-    }
-    return c.JSON(user)
-}
-
-func createUser(c fiber.Ctx) error {
-    var req CreateUserRequest
-    if err := c.BodyParser(&req); err != nil {
-        return fiber.NewError(fiber.StatusBadRequest, "Invalid request body")
-    }
-    if err := validate.Struct(&req); err != nil {
-        return NewValidationError(err)
-    }
-
-    user, err := userService.Create(c.UserContext(), req)
-    if err != nil {
-        var pgErr *pgconn.PgError
-        if errors.As(err, &pgErr) && pgErr.Code == "23505" {
-            return &ConflictError{Resource: "User", Field: "email", Value: req.Email}
-        }
-        return err
-    }
-
-    return c.Status(fiber.StatusCreated).JSON(user)
-}
-```
-
-## Panic Recovery
-
-The recover middleware catches panics and feeds them to the ErrorHandler.
-
-```go
-import "github.com/gofiber/fiber/v3/middleware/recover"
-
-app.Use(recover.New(recover.Config{
-    EnableStackTrace: true,
-    StackTraceHandler: func(c fiber.Ctx, e interface{}) {
-        // Log the panic with stack trace
-        slog.Error("panic recovered",
-            "error", e,
-            "stack", string(debug.Stack()),
-            "path", c.Path(),
-            "method", c.Method(),
-        )
-    },
-}))
-```
-
-## Error Wrapping for Context
-
-Wrap errors with additional context as they bubble up through service layers.
-
-```go
-// Service layer
-func (s *UserService) Create(ctx context.Context, req CreateUserRequest) (*User, error) {
-    user, err := s.repo.Insert(ctx, req)
-    if err != nil {
-        return nil, fmt.Errorf("create user: %w", err)
-    }
-    return user, nil
-}
-
-// The ErrorHandler uses errors.As to unwrap and find known error types
-// even when they are wrapped with fmt.Errorf("%w", ...)
-```
-
-## HTTP Status Code Mapping
-
-| Error Type | HTTP Status | Code String |
-| --- | --- | --- |
-| `*fiber.Error` | from error | mapped from status |
-| `*ValidationError` | 400 | VALIDATION_ERROR |
-| `*NotFoundError` | 404 | NOT_FOUND |
-| `*AuthError` | 401 | UNAUTHORIZED |
-| `*ConflictError` | 409 | CONFLICT |
-| Unhandled error | 500 | INTERNAL_ERROR |
-| Panic (recovered) | 500 | INTERNAL_ERROR |