groundwork-method 0.0.1 → 0.10.0

package/src/generators/go-microservice/files/go.mod.template

@@ -0,0 +1,39 @@
+module <%= name %>
+
+go 1.22.0
+
+require (
+	github.com/danielgtaylor/huma/v2 v2.34.1
+	github.com/go-chi/chi/v5 v5.2.2
+	github.com/go-chi/cors v1.2.2
+	github.com/rs/zerolog v1.34.0
+	github.com/joho/godotenv v1.5.1
+	go.opentelemetry.io/otel v1.24.0
+	go.opentelemetry.io/otel/trace v1.24.0
+	go.opentelemetry.io/otel/sdk v1.24.0
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.24.0
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.24.0
+	go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc v1.24.0
+	go.opentelemetry.io/otel/metric v1.24.0
+	go.opentelemetry.io/otel/sdk/metric v1.24.0
+	github.com/stripe/pg-schema-diff v1.0.5
+	github.com/lib/pq v1.10.9
+<% if (auth === 'clerk') { %>
+	github.com/clerk/clerk-sdk-go/v2 v2.5.1
+	github.com/svix/svix-webhooks v1.90.0
+<% } %>
+<% if (websockets) { %>
+	github.com/gorilla/websocket v1.5.3
+<% } %>
+<% if (messaging === 'kafka') { %>
+	github.com/confluentinc/confluent-kafka-go/v2 v2.14.1
+<% } else if (messaging === 'gcp-pubsub') { %>
+	cloud.google.com/go/pubsub v1.37.0
+<% } %>
+	github.com/sony/gobreaker v1.0.0
+	github.com/cenkalti/backoff/v4 v4.3.0
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0
+	github.com/stretchr/testify v1.9.0
+	github.com/testcontainers/testcontainers-go v0.29.1
+	github.com/testcontainers/testcontainers-go/modules/postgres v0.29.1
+)

package/src/generators/go-microservice/files/internal/config/config.go.template

@@ -0,0 +1,52 @@
+package config
+
+import (
+	"log"
+
+	"github.com/caarlos0/env/v11"
+)
+
+type Config struct {
+	Server    ServerConfig
+	Database  DatabaseConfig
+	Redis     RedisConfig
+	Telemetry TelemetryConfig
+<% if (auth === 'clerk') { %>
+	Auth      AuthConfig
+<% } %>
+}
+
+<% if (auth === 'clerk') { %>
+type AuthConfig struct {
+	// No default: a missing secret leaves this empty so the webhook handler
+	// fails loud ("not configured") rather than masquerading as a configured
+	// service with a stub secret that silently rejects every signature.
+	ClerkWebhookSecret string `env:"CLERK_WEBHOOK_SIGNING_SECRET"`
+}
+<% } %>
+
+type ServerConfig struct {
+	Port int `env:"PORT" envDefault:"8080"`
+}
+
+type DatabaseConfig struct {
+	URI string `env:"DATABASE_URL" envDefault:"postgres://postgres:postgres@localhost:5432/<%= name %>?sslmode=disable"`
+}
+
+type RedisConfig struct {
+	URI string `env:"REDIS_URL"` // Optional: If set, enables Valkey/Redis for backplane and rate limiting
+}
+
+type TelemetryConfig struct {
+	// Per the OTLP spec this carries a scheme (e.g. http://otel-host:4317).
+	// InitProvider parses it with WithEndpointURL, which is scheme-aware.
+	CollectorURL string `env:"OTEL_EXPORTER_OTLP_ENDPOINT" envDefault:"http://localhost:4317"`
+}
+
+func Load() *Config {
+	var cfg Config
+	if err := env.Parse(&cfg); err != nil {
+		log.Fatalf("failed to load configuration: %v", err)
+	}
+	return &cfg
+}

package/src/generators/go-microservice/files/internal/config/otel.go.template

@@ -0,0 +1,93 @@
+package config
+
+import (
+	"context"
+	"fmt"
+
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc"
+	"go.opentelemetry.io/otel/exporters/otlp/otlptrace"
+	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
+	"go.opentelemetry.io/otel/propagation"
+	"go.opentelemetry.io/otel/sdk/resource"
+	sdkmetric "go.opentelemetry.io/otel/sdk/metric"
+	sdktrace "go.opentelemetry.io/otel/sdk/trace"
+	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
+)
+
+// InitProvider initializes an OpenTelemetry trace provider connected to an OTLP endpoint.
+func InitProvider(ctx context.Context, serviceName, collectorURL string) (func(context.Context) error, error) {
+	if collectorURL == "" {
+		// Use default standard OTEL environment variables if no URL is provided
+		collectorURL = "http://localhost:4317"
+	}
+
+	res, err := resource.Merge(
+		resource.Default(),
+		resource.NewWithAttributes(
+			"", // Use empty schemaURL to inherit from resource.Default()
+			semconv.ServiceName(serviceName),
+		),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("merge otel resources: %w", err)
+	}
+
+	// WithEndpointURL is scheme-aware and accepts the full OTLP endpoint URL
+	// (e.g. http://otel-host:4317). WithEndpoint, by contrast, wants a bare
+	// host:port and silently mis-dials when handed an http:// value.
+	client := otlptracegrpc.NewClient(
+		otlptracegrpc.WithEndpointURL(collectorURL),
+		otlptracegrpc.WithInsecure(),
+	)
+
+	exporter, err := otlptrace.New(ctx, client)
+	if err != nil {
+		return nil, fmt.Errorf("create otel exporter: %w", err)
+	}
+
+	tp := sdktrace.NewTracerProvider(
+		sdktrace.WithBatcher(exporter),
+		sdktrace.WithResource(res),
+	)
+
+	otel.SetTracerProvider(tp)
+	otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(
+		propagation.TraceContext{},
+		propagation.Baggage{},
+	))
+
+	// --- Metrics ---
+	// The otelhttp middleware records baseline HTTP server metrics (request
+	// count, latency histogram, active in-flight requests) automatically once a
+	// global MeterProvider is registered. Export them over OTLP gRPC on a
+	// periodic reader to the same collector as traces.
+	metricExporter, err := otlpmetricgrpc.New(ctx,
+		otlpmetricgrpc.WithEndpointURL(collectorURL),
+		otlpmetricgrpc.WithInsecure(),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("create otel metric exporter: %w", err)
+	}
+
+	mp := sdkmetric.NewMeterProvider(
+		sdkmetric.WithReader(sdkmetric.NewPeriodicReader(metricExporter)),
+		sdkmetric.WithResource(res),
+	)
+	otel.SetMeterProvider(mp)
+
+	// Combined shutdown: flush and close both providers. The returned signature
+	// is unchanged, so main.go's `defer otelShutdown(ctx)` call is untouched.
+	shutdown := func(ctx context.Context) error {
+		var firstErr error
+		if err := tp.Shutdown(ctx); err != nil {
+			firstErr = err
+		}
+		if err := mp.Shutdown(ctx); err != nil && firstErr == nil {
+			firstErr = err
+		}
+		return firstErr
+	}
+
+	return shutdown, nil
+}

package/src/generators/go-microservice/files/internal/core/domain/errors.go.template

@@ -0,0 +1,16 @@
+package domain
+
+import "errors"
+
+// Standard Sentinel Errors
+// These errors should be used across the core domain to represent
+// business logic failures, allowing entrypoints (like HTTP routers)
+// to map them to the appropriate status codes.
+
+var (
+	ErrNotFound       = errors.New("resource not found")
+	ErrConflict       = errors.New("resource already exists")
+	ErrUnauthorized   = errors.New("unauthorized action")
+	ErrInvalidPayload = errors.New("invalid payload provided")
+	ErrInternal       = errors.New("internal server error")
+)

package/src/generators/go-microservice/files/internal/core/domain/model.go.template

@@ -0,0 +1,28 @@
+package domain
+
+import "time"
+
+// Entity represents a basic domain model.
+// Replace this with your actual business entities.
+type Entity struct {
+	ID        string    `json:"id"`
+	Name      string    `json:"name"`
+	CreatedAt time.Time `json:"created_at"`
+	UpdatedAt time.Time `json:"updated_at"`
+}
+
+// OutboxEvent represents a serialized event to be published
+// via the Transactional Outbox pattern.
+type OutboxEvent struct {
+	ID        string `json:"id"`
+	EventType string `json:"event_type"`
+	Payload   []byte `json:"payload"`
+	CreatedAt int64  `json:"created_at"`
+}
+
+// Event represents a generic domain event used for synchronous
+// broadcasting to connected clients (e.g., via WebSocket hub).
+type Event struct {
+	Type    string `json:"type"`
+	Payload any    `json:"payload"`
+}

package/src/generators/go-microservice/files/internal/core/domain/user.go.template

@@ -0,0 +1,13 @@
+package domain
+
+import "time"
+
+// User represents a synced user from an external Auth provider (e.g., Clerk)
+type User struct {
+	ID        string
+	ClerkID   string
+	Email     string
+	Username  string
+	CreatedAt time.Time
+	UpdatedAt time.Time
+}

package/src/generators/go-microservice/files/internal/core/pagination.go.template

@@ -0,0 +1,16 @@
+package core
+
+// PageRequest models a standard cursor-based pagination request.
+type PageRequest struct {
+	Cursor string `json:"cursor" query:"cursor" description:"Opaque cursor for the next page of results"`
+	Limit  int    `json:"limit" query:"limit" description:"Maximum number of items to return" default:"50"`
+}
+
+// PageResponse is a generic container for paginated collections, ensuring all API
+// lists return the same shape.
+type PageResponse[T any] struct {
+	Items      []T    `json:"items" description:"The collection of items"`
+	NextCursor string `json:"nextCursor,omitempty" description:"Opaque cursor to retrieve the next page, omitted if there are no more pages"`
+	PrevCursor string `json:"prevCursor,omitempty" description:"Opaque cursor to retrieve the previous page"`
+	HasMore    bool   `json:"hasMore" description:"True if there are more items beyond the next cursor"`
+}

package/src/generators/go-microservice/files/internal/core/service/app_service.go.template

@@ -0,0 +1,79 @@
+package service
+
+import (
+	"context"
+	"fmt"
+
+	"<%= name %>/internal/core/domain"
+)
+
+// AppService orchestrates business use-cases, coordinating between
+// domain entities, database transactions, and message publishing.
+//
+// The interfaces it depends on (TransactionManager, Repository, EventHub,
+// OutboxRepository) are declared in this package — the consumer owns the
+// interface it needs, and adapters in internal/postgres, internal/kafka, etc.
+// satisfy them implicitly. The dependency arrow points inward (edge -> core),
+// enforced by depguard.
+type AppService struct {
+	txManager TransactionManager
+	repo      Repository[domain.Entity]
+	eventHub  EventHub
+<% if (messaging !== 'none') { %>
+	outbox    OutboxRepository
+<% } %>
+}
+
+// NewAppService creates a new instance of the application service.
+func NewAppService(
+	txManager TransactionManager,
+	repo Repository[domain.Entity],
+	eventHub EventHub,
+<% if (messaging !== 'none') { %>
+	outbox OutboxRepository,
+<% } %>
+) *AppService {
+	return &AppService{
+		txManager: txManager,
+		repo:      repo,
+		eventHub:  eventHub,
+<% if (messaging !== 'none') { %>
+		outbox:    outbox,
+<% } %>
+	}
+}
+
+// ExecuteUseCase demonstrates a standard transactional use-case.
+func (s *AppService) ExecuteUseCase(ctx context.Context, entity *domain.Entity) error {
+	// Begin transaction
+	tx, err := s.txManager.Begin(ctx)
+	if err != nil {
+		return fmt.Errorf("begin transaction: %w", err)
+	}
+	defer tx.Rollback(ctx)
+
+	// Perform business logic (e.g., save to DB)
+	if err := s.repo.Create(ctx, entity); err != nil {
+		return fmt.Errorf("create entity: %w", err)
+	}
+
+<% if (messaging !== 'none') { %>
+	// Insert domain event into the outbox within the same transaction
+	if err := s.outbox.InsertEvent(ctx, tx, "EntityCreated", []byte(`{"id":"`+entity.ID+`"}`)); err != nil {
+		return fmt.Errorf("insert outbox event: %w", err)
+	}
+<% } %>
+
+	// Commit transaction
+	if err := tx.Commit(ctx); err != nil {
+		return fmt.Errorf("commit transaction: %w", err)
+	}
+
+	// Broadcast the domain event synchronously to live clients
+	s.eventHub.Broadcast(domain.Event{
+		Type:    "entity.created",
+		Payload: entity,
+	})
+
+	return nil
+}

package/src/generators/go-microservice/files/internal/core/service/event_hub.go.template

@@ -0,0 +1,9 @@
+package service
+
+import "<%= name %>/internal/core/domain"
+
+// EventHub defines an interface for synchronously broadcasting domain events
+// to connected clients (e.g., via WebSockets).
+type EventHub interface {
+	Broadcast(event domain.Event)
+}

package/src/generators/go-microservice/files/internal/core/service/message_queue.go.template

@@ -0,0 +1,10 @@
+<% if (messaging !== 'none') { %>package service
+
+import "context"
+
+// MessageQueue defines operations for publishing domain messages
+// to an asynchronous message bus or queue.
+type MessageQueue interface {
+	Publish(ctx context.Context, topic string, key, data []byte) error
+}
+<% } %>

package/src/generators/go-microservice/files/internal/core/service/outbox_repository.go.template

@@ -0,0 +1,31 @@
+<% if (messaging !== 'none') { %>package service
+
+import (
+	"context"
+)
+
+// OutboxEvent represents a serialized domain event stored in the outbox table.
+type OutboxEvent struct {
+	ID        string
+	EventType string
+	Payload   []byte
+	CreatedAt int64
+}
+
+// OutboxRepository manages transactional outbox events.
+// Events are inserted in the same DB transaction as domain mutations,
+// then published asynchronously by a background relay.
+type OutboxRepository interface {
+	// InsertEvent inserts an outbox event. The implementation is responsible
+	// for managing its own transactional context when needed.
+	InsertEvent(ctx context.Context, tx Transaction, eventType string, payload []byte) error
+
+	// PollUnpublished returns up to `limit` unpublished events, oldest first.
+	// The implementation must ensure row-level locking within a transaction
+	// to prevent duplicate processing by concurrent relay instances.
+	PollUnpublished(ctx context.Context, limit int) ([]OutboxEvent, error)
+
+	// MarkPublished marks an outbox event as published.
+	MarkPublished(ctx context.Context, id string) error
+}
+<% } %>

package/src/generators/go-microservice/files/internal/core/service/repository.go.template

@@ -0,0 +1,23 @@
+package service
+
+import "context"
+
+// Repository defines a standard generic interface for data access.
+type Repository[T any] interface {
+	GetByID(ctx context.Context, id string) (*T, error)
+	Create(ctx context.Context, entity *T) error
+	Update(ctx context.Context, entity *T) error
+	Delete(ctx context.Context, id string) error
+}
+
+// Transaction represents an active database transaction.
+type Transaction interface {
+	Commit(ctx context.Context) error
+	Rollback(ctx context.Context) error
+}
+
+// TransactionManager defines an interface for managing database transactions.
+// This is typically injected into application services to wrap domain use-cases.
+type TransactionManager interface {
+	Begin(ctx context.Context) (Transaction, error)
+}

package/src/generators/go-microservice/files/internal/core/service/user_repository.go.template

@@ -0,0 +1,15 @@
+package service
+
+import (
+	"context"
+
+	"<%= name %>/internal/core/domain"
+)
+
+// UserRepository defines the interface for user data access
+type UserRepository interface {
+	GetByClerkID(ctx context.Context, clerkID string) (*domain.User, error)
+	Save(ctx context.Context, user *domain.User) error
+	Update(ctx context.Context, user *domain.User) error
+	DeleteByClerkID(ctx context.Context, clerkID string) error
+}

package/src/generators/go-microservice/files/internal/core/service/user_service.go.template

@@ -0,0 +1,43 @@
+package service
+
+import (
+	"context"
+	"fmt"
+
+	"<%= name %>/internal/core/domain"
+)
+
+type UserService struct {
+	repo UserRepository
+}
+
+func NewUserService(repo UserRepository) *UserService {
+	return &UserService{
+		repo: repo,
+	}
+}
+
+func (s *UserService) GetByClerkID(ctx context.Context, clerkID string) (*domain.User, error) {
+	return s.repo.GetByClerkID(ctx, clerkID)
+}
+
+func (s *UserService) Save(ctx context.Context, user *domain.User) error {
+	if err := s.repo.Save(ctx, user); err != nil {
+		return fmt.Errorf("failed to save user: %w", err)
+	}
+	return nil
+}
+
+func (s *UserService) Update(ctx context.Context, user *domain.User) error {
+	if err := s.repo.Update(ctx, user); err != nil {
+		return fmt.Errorf("failed to update user: %w", err)
+	}
+	return nil
+}
+
+func (s *UserService) DeleteByClerkID(ctx context.Context, clerkID string) error {
+	if err := s.repo.DeleteByClerkID(ctx, clerkID); err != nil {
+		return fmt.Errorf("failed to delete user by clerk id: %w", err)
+	}
+	return nil
+}

package/src/generators/go-microservice/files/internal/entrypoints/api/app_handler.go.template

@@ -0,0 +1,108 @@
+package api
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"time"
+
+	"github.com/danielgtaylor/huma/v2"
+
+	"<%= name %>/internal/core/domain"
+	"<%= name %>/internal/core/service"
+)
+
+type CreateEntityRequest struct {
+	Body struct {
+		Name string `json:"name" doc:"Name of the entity"`
+	}
+}
+
+type CreateEntityResponse struct {
+	Body struct {
+		ID string `json:"id"`
+	}
+}
+
+type ListEntitiesRequest struct {
+	Limit  int    `query:"limit" default:"20" minimum:"1" maximum:"100" doc:"Number of items to return"`
+	Cursor string `query:"cursor" required:"false" doc:"Cursor for pagination"`
+}
+
+type ListEntitiesResponse struct {
+	Body struct {
+		Data       []*domain.Entity   `json:"data"`
+		Pagination paginationEnvelope `json:"pagination"`
+	}
+}
+
+// RegisterAppHandler demonstrates how to register endpoints mapped to use-cases in AppService.
+func RegisterAppHandler(api huma.API, appSvc *service.AppService) {
+	huma.Register(api, huma.Operation{
+		OperationID: "create-entity",
+		Method:      http.MethodPost,
+		Path:        "/api/v1/entities",
+		Summary:     "Create a new entity",
+		Description: "Creates a new domain entity and returns its ID.",
+		Tags:        []string{"Entities"},
+	}, func(ctx context.Context, input *CreateEntityRequest) (*CreateEntityResponse, error) {
+		
+		entity := &domain.Entity{
+			ID:   "gen-id-123", // STUB: use uuid.New()
+			Name: input.Body.Name,
+		}
+
+		if err := appSvc.ExecuteUseCase(ctx, entity); err != nil {
+			if errors.Is(err, domain.ErrConflict) {
+				return nil, huma.Error409Conflict("Entity already exists", err)
+			}
+			return nil, huma.Error500InternalServerError("Internal server error", err)
+		}
+
+		resp := &CreateEntityResponse{}
+		resp.Body.ID = entity.ID
+		return resp, nil
+	})
+
+	huma.Register(api, huma.Operation{
+		OperationID: "list-entities",
+		Method:      http.MethodGet,
+		Path:        "/api/v1/entities",
+		Summary:     "List entities",
+		Description: "Returns a paginated list of entities.",
+		Tags:        []string{"Entities"},
+	}, func(ctx context.Context, input *ListEntitiesRequest) (*ListEntitiesResponse, error) {
+		
+		// 1. Decode Cursor
+		var afterID string
+		var afterCreatedAt time.Time
+		if payload := decodeCursor(input.Cursor); payload != nil {
+			afterID = payload.ID
+			afterCreatedAt = payload.CreatedAt
+		}
+		
+		_ = afterID
+		_ = afterCreatedAt
+
+		// STUB: Use afterID, afterCreatedAt and input.Limit to fetch items. 
+		// Example: items, err := appSvc.ListEntities(ctx, afterID, afterCreatedAt, input.Limit+1)
+		
+		// For demonstration, we create a mock list
+		now := time.Now()
+		items := []*domain.Entity{
+			{ID: "ent-1", Name: "First", CreatedAt: now.Add(-1 * time.Hour)},
+			{ID: "ent-2", Name: "Second", CreatedAt: now.Add(-2 * time.Hour)},
+		}
+
+		// 2. Build Pagination
+		data, pagination := buildPagination(items, input.Limit, 
+			func(e *domain.Entity) string { return e.ID }, 
+			func(e *domain.Entity) time.Time { return e.CreatedAt },
+		)
+
+		resp := &ListEntitiesResponse{}
+		resp.Body.Data = data
+		resp.Body.Pagination = pagination
+		return resp, nil
+	})
+}

package/src/generators/go-microservice/files/internal/entrypoints/api/auth_middleware_test.go.template

@@ -0,0 +1,52 @@
+<% if (auth === 'clerk') { %>package api
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func protectedHandler() http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte("protected"))
+	})
+}
+
+// NOTE on status codes: Clerk's clerkhttp.RequireHeaderAuthorization (v2) responds
+// with HTTP 403 Forbidden — NOT 401 — when the Authorization header is missing or
+// carries an unverifiable token (it short-circuits before reaching the wrapped
+// handler that would otherwise emit 401). No Clerk secret key is required for these
+// paths: a missing token never decodes a JWT, and a malformed token fails
+// jwt.Decode locally before any key/JWKS lookup, so both surface 403 offline.
+
+func TestAuthMiddleware_BypassesHealthAndWebhooks(t *testing.T) {
+	h := AuthMiddleware()(protectedHandler())
+
+	for _, path := range []string{"/health", "/webhooks/clerk"} {
+		rr := httptest.NewRecorder()
+		h.ServeHTTP(rr, httptest.NewRequest(http.MethodGet, path, nil))
+		require.Equal(t, http.StatusOK, rr.Code, "auth must bypass %s", path)
+	}
+}
+
+func TestAuthMiddleware_RejectsMissingToken(t *testing.T) {
+	// No Authorization header on a protected route -> Clerk's RequireHeaderAuthorization
+	// rejects with 403 before reaching the inner handler.
+	h := AuthMiddleware()(protectedHandler())
+	rr := httptest.NewRecorder()
+	h.ServeHTTP(rr, httptest.NewRequest(http.MethodGet, "/api/v1/entities", nil))
+	require.Equal(t, http.StatusForbidden, rr.Code)
+}
+
+func TestAuthMiddleware_RejectsBadToken(t *testing.T) {
+	h := AuthMiddleware()(protectedHandler())
+	rr := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/entities", nil)
+	req.Header.Set("Authorization", "Bearer not-a-real-jwt")
+	h.ServeHTTP(rr, req)
+	require.Equal(t, http.StatusForbidden, rr.Code, "an unverifiable token must not pass")
+}
+<% } %>